# HereGo docs

Connect AI agents over Model Context Protocol, or integrate directly with the REST API. MCP is the fastest path — it is a stateless adapter over the same REST endpoints, so everything you can do in REST is one tool call away.

## Start here

- **MCP Server** (recommended): https://herego.video/docs/mcp — three tools over Streamable HTTP: `request_video_evidence`, `get_video_evidence`, `delete_video_request`.
- **REST API**: https://herego.video/docs/api — `POST /v1/requests`, `GET /v1/requests/{id}`, `DELETE /v1/requests/{id}`, `GET /v1/videos/{id}`.

## Quickstart

Both paths start the same way: create a request, share the link, retrieve the video.

### MCP quickstart (recommended)

No account, no API key, no MCP-level authentication. Point your MCP client at
`https://herego.video/mcp`:

```json
{
  "mcpServers": {
    "herego": {
      "url": "https://herego.video/mcp"
    }
  }
}
```

1. **Generate video submission request** — call `request_video_evidence`:

```json
{
  "prompt": "Please show me what happens when you try to check out.",
  "expires_in_hours": 24
}
```

Result:

```json
{
  "id": "req_abc123",
  "status": "awaiting_submission",
  "submission_url": "https://herego.video/r/abc123",
  "access_token": "rat_9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d",
  "expires_at": "2026-09-08T14:30:00Z"
}
```

2. **Check video submission status and retrieve video** — call `get_video_evidence`:

```json
{
  "request_id": "req_abc123",
  "access_token": "rat_9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d"
}
```

Result:

```json
{
  "request_id": "req_abc123",
  "status": "submitted",
  "expires_at": "2026-09-08T14:30:00Z",
  "video": {
    "mime_type": "video/webm",
    "size": 482113
  }
}
// + the actual video attached as MCP media content
```

3. **Delete video request** — call `delete_video_request`:

```json
{
  "request_id": "req_abc123",
  "access_token": "rat_9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d"
}
```

Result:

```json
{
  "request_id": "req_abc123",
  "deleted": true
}
```

### REST quickstart

No API key is required. Every request after creation sends the request-scoped token returned by POST /v1/requests as `Authorization: Bearer <token>`.

1. **Create a video request** — `POST /v1/requests`

Create a video request and receive a human submission URL plus a request-scoped access token.

```bash
curl -X POST https://herego.video/v1/requests \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Please show me what happens when you try to check out.",
    "expires_in_hours": 24
  }'
```

Response `201`:

```json
{
  "id": "req_abc123",
  "status": "awaiting_submission",
  "submission_url": "https://herego.video/r/abc123",
  "access_token": "rat_9f8b7c6d5e4f3a2b1c0d9e8f7a6b5c4d",
  "expires_at": "2026-09-08T14:30:00Z"
}
```

2. **Share the link, then poll for status** — `GET /v1/requests/{id}`

Give the submission URL to the human, then poll with the request access token until the status becomes submitted.

```bash
curl https://herego.video/v1/requests/req_abc123 \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

Response `200`:

```json
{
  "id": "req_abc123",
  "status": "submitted",
  "expires_at": "2026-09-08T14:30:00Z",
  "video": {
    "id": "vid_xyz789",
    "url": "https://herego.video/v1/videos/vid_xyz789",
    "expires_at": "2026-09-08T14:30:00Z"
  }
}
```

3. **Stream the submitted video** — `GET /v1/videos/{id}`

Stream the video bytes with the same request access token. Byte-range requests are supported for seeking.

```bash
curl https://herego.video/v1/videos/vid_xyz789 \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Range: bytes=0-1048575" --output evidence.webm
```

Response `206`:

```json
Content-Type: video/webm
Content-Length: 482113
Accept-Ranges: bytes

<binary video bytes>
```

4. **Delete the request when you're done** — `DELETE /v1/requests/{id}`

Delete the entire request and its submitted video. The response body is empty.

```bash
curl -X DELETE https://herego.video/v1/requests/req_abc123 \
  -H "Authorization: Bearer $ACCESS_TOKEN" -i
```

Response `204`:

```
// 204 No Content — empty response body
```

## Resources

- Machine-readable discovery: https://herego.video/api
- OpenAPI specification: https://herego.video/api/openapi.json
- Agent quickstart: https://herego.video/llms.txt