# The API, in detail.

The implemented beta endpoints, generated from the same [OpenAPI contract](/openapi.json) you can import into your development tools. All requests require a workspace bearer key.

## Upload a FIT activity

`POST /v1/activities`

Send raw FIT bytes, not multipart or JSON. Maximum 4 MiB. The same bytes in the same workspace reuse one activity. HTTP 202 means processing is pending; 200 means the returned activity is already ready or failed. Concurrent uploads converge on one ID; duplicate is advisory.

**Body:** raw FIT bytes, maximum 4 MiB. Content-Type: `application/vnd.ant.fit` or `application/octet-stream`.

| HTTP | Response |
| --- | --- |
| `200` | Existing terminal activity |
| `202` | Activity accepted for asynchronous processing |
| `400` | Invalid request |
| `401` | Missing, invalid, or revoked key |
| `413` | File exceeds 4 MiB |
| `415` | Unsupported media type |
| `422` | FIT validation failed |
| `503` | Service or stored object unavailable; hosted beta may not be open |

## List activities

`GET /v1/activities`

Workspace-scoped, newest first (created_at then id, both descending). Offset pages can shift when new activities are added. stats always describes the entire workspace, independent of filters.

| Parameter | Location | Details |
| --- | --- | --- |
| `q` | query | Case-sensitive activity ID substring; trimmed  |
| `status` | query | processing combines received and queued Values: received, queued, processing, ready, failed. |
| `limit` | query |   Range: 1–100. Default: 20. |
| `offset` | query |   Range: 0–100000. Default: 0. |

| HTTP | Response |
| --- | --- |
| `200` | Matching activities and workspace counts |
| `400` | Invalid request |
| `401` | Missing, invalid, or revoked key |
| `503` | Service or stored object unavailable; hosted beta may not be open |

## Read activity status

`GET /v1/activities/{id}`



| Parameter | Location | Details |
| --- | --- | --- |
| `id` | path · required | Activity ID returned by upload  |

| HTTP | Response |
| --- | --- |
| `200` | Activity metadata; check status for processing state |
| `401` | Missing, invalid, or revoked key |
| `404` | Unknown resource or inaccessible workspace |
| `503` | Service or stored object unavailable; hosted beta may not be open |

## Retrieve decoded JSON

`GET /v1/activities/{id}/data`

Available only for ready activities. FIT SDK field names and units are retained; source-dependent message fields are intentionally open.

| Parameter | Location | Details |
| --- | --- | --- |
| `id` | path · required | Activity ID returned by upload  |

| HTTP | Response |
| --- | --- |
| `200` | Decoded FIT messages |
| `401` | Missing, invalid, or revoked key |
| `404` | Unknown resource or inaccessible workspace |
| `409` | Data not ready or decoding failed |
| `503` | Service or stored object unavailable; hosted beta may not be open |

## Download untouched original

`GET /v1/activities/{id}/original`

Available even when decoding failed. Compare its SHA-256 with the activity metadata and your source.

| Parameter | Location | Details |
| --- | --- | --- |
| `id` | path · required | Activity ID returned by upload  |

| HTTP | Response |
| --- | --- |
| `200` | Exact uploaded FIT bytes |
| `401` | Missing, invalid, or revoked key |
| `404` | Unknown resource or inaccessible workspace |
| `503` | Service or stored object unavailable; hosted beta may not be open |

## Response schemas

See the [data model](/docs/data-model) for field meanings and the [OpenAPI JSON](/openapi.json) for complete machine-readable response schemas. The downloadable contract includes only implemented server endpoints.