Background operations
Work that can take longer than a request is accepted with 202 Accepted and runs in the background as a job. The 202 answers only "queued". Every job has an id, and its outcome is read at GET /jobs/{job_id}, which you poll. All paths are under /api/v1.
Every job answers the same envelope, so a client reads one vocabulary whatever the job is. Read the table first, then the section of the operation you call.
| Member | Meaning |
|---|---|
id |
The job's identifier, a UUID |
kind |
What the job does, from the table below. It also tells which other members the job carries |
status |
queued, running, succeeded or failed, for every kind of job |
error_code |
Why the job failed, from a closed set per kind. null unless status is failed, and for a kind that records no reason |
created_at, finished_at |
When the job was accepted and when it reached succeeded or failed (null until then) |
Each kind adds its own members to the envelope: mfa_required on the Garmin Connect link, size_bytes and expires_at on an export, imported on a profile import and the members listed under Activity ingestion jobs.
Every 202 carries the job in its body and two headers:
Content-Locationis the path of the job,/api/v1/jobs/{job_id}.Retry-Afteris the number of seconds to wait before the first poll.
The only 202 whose job you cannot read is your own account deletion.
| Operation | Start | kind |
Idempotency-Key |
|---|---|---|---|
| Upload an activity file | POST /activities/upload |
activity_upload |
Yes |
| Import a ZIP archive of activity files | POST /activities/bulk-import |
activity_bulk_import |
Yes |
| Import the files in your folder on the server | POST /activities/bulk-import/folder |
activity_bulk_import |
No |
| Sync linked providers (last 24 hours) | POST /activities/refresh |
activity_refresh |
No |
| Sync Garmin Connect or Strava activities for a date range | POST /garmin/activities, POST /strava/activities |
activity_refresh |
No |
| Link Garmin Connect | POST /garmin/link |
garmin_link |
No |
| Sync Garmin Connect gear or health | POST /garmin/gear, POST /garmin/health |
garmin_sync_gear, garmin_sync_health |
No |
| Link Strava | POST /strava/link |
strava_link |
No |
| Sync Strava gear | POST /strava/gear |
strava_gear |
No |
| Unlink Strava | POST /strava/unlink |
strava_unlink |
No |
| Export your profile | POST /profile/export |
profile_export |
No |
| Import a profile | POST /profile/import |
profile_import |
No |
| Bulk edit activity visibility | PATCH /activities |
activities_bulk_edit |
No |
| Delete a gear | DELETE /gears/{gear_id} |
gear_deletion |
No |
| Delete a user (administrators) | POST /users/{user_id}/delete |
user_deletion |
No |
| Delete your account | POST /profile/delete-account |
user_deletion, not readable, see below |
No |
The activity upload and the archive bulk import take an Idempotency-Key. Every other start route refuses a second request while one of the same kind is still running (see 409), which is what protects a retry.
Reading a job
GET /jobs/{job_id} reads one job. Poll the path that Content-Location names, and wait the seconds in Retry-After between polls (slower while a realtime hint connection is open). A job that is not finished sends Retry-After again; a final state, succeeded or failed, sends none, so stop there.
- Reading a job needs the scope of the route that starts it:
activities:uploadfor an activity upload,activities:writefor a refresh, a bulk import or a bulk edit,gears:writefor a gear deletion or a Garmin Connect or Strava gear sync,health:writefor a Garmin Connect health sync,account:integrationsfor a Garmin Connect link or a Strava link or unlink,account:exportfor a profile export or import, andusers:read-allfor an account deletion. Without it the read is403. - You read the jobs you started. Any administrator with
users:read-allcan also read an account deletion. Another user's job is404, never403, so an id cannot be probed. - An id that is not a UUID is
422. An unknown well-formed id is404. So is a job whose record has expired. An activity ingestion job is kept for its retention period. Every other job is kept for a limited time after it starts: 7 minutes for a Garmin Connect link, 30 minutes for a Garmin Connect or Strava sync or a Strava link or unlink, 1 hour for a bulk edit or a gear deletion, 2 hours for a profile export or an account deletion and 4 hours for a profile import. Starting the next job of the same kind replaces it sooner. Poll until a final state and do not rely on reading the result later. - A
202can also be refused with503when the server runs without a durable job worker and its in-process pool is full. Retry later.
Listing your jobs
GET /jobs lists the jobs you started, newest first, as a keyset page: items, num_records and next_cursor. Pass next_cursor back as cursor for the next slice; num_records sets the slice size. Filter with kind (one of the values above) and status. Only the kinds your scopes can read are listed, so an API key with only activities:upload sees its uploads alone.
Use it to pick a job up again when the client lost its id, for example after a restart: GET /jobs?kind=profile_export finds the export to download, and GET /jobs?status=running the work still in progress. A job is listed for as long as it can be read.
Activity ingestion jobs
These routes start a job of one shape, ActivityIngestionJobRead, whatever the source of the activities.
{
"id": "0c0f8e0e-3f0b-4a50-9a58-6a1d0a2d5d11",
"kind": "activity_upload",
"filename": "morning-run.fit",
"status": "succeeded",
"error_code": null,
"activity_ids": ["7c9e6679-7425-40de-944b-e07fc1f90ae7"],
"created_at": "2026-11-05T07:30:00Z",
"updated_at": "2026-11-05T07:30:04Z",
"finished_at": "2026-11-05T07:30:04Z"
}
| Member | Meaning |
|---|---|
kind |
activity_upload, activity_bulk_import or activity_refresh |
status |
queued, running, succeeded or failed |
error_code |
Set when status is failed: unsupported_format, invalid_file, no_activities_found, processing_failed or provider_unavailable |
activity_ids |
The activities the job created, once it succeeds |
files_total, files_done, files_failed |
Bulk import progress. A finished import with failed files still ends succeeded |
import_source |
The archive layout of a bulk import |
provider |
The provider a refresh syncs. Empty when it syncs every linked provider |
retry_after |
When a refresh that is waiting for a provider's rate limit runs again |
finished_at |
When the job reached succeeded or failed |
A refresh that is waiting for a provider's rate limit to clear is queued with retry_after set. It is not a failure: the job runs again by itself at retry_after.
Reading an upload job needs the activities:upload scope. Starting a bulk import, a folder import, a refresh or a provider range sync needs activities:write, and so does reading its job. Each accepts a bearer token or an API key holding the scope.
Upload an activity file
POST /activities/upload, a multipart form with the file in file. It needs the activities:upload scope and accepts a bearer token or an API key. The file is stored and queued, then the route answers 202 with the job. Cheap refusals come back at once as errors instead of a job: an unsupported extension or a file whose content is not that type is 415, a file over the limit is 413, and a file that is empty or fails the other content checks is 400.
A user may have at most 10 uploads open at once, counting those pending, processing or deferred. The 11th is 409 with urn:endurain:error:conflict and a detail that names the limit. It is refused before the file is stored, and no job is created. Poll your open uploads until one finishes, then upload again. A replay with an Idempotency-Key that already has a job answers with that job even at the limit.
Send an Idempotency-Key header (up to 255 characters) to make a retry safe. A client that never saw the 202 has no job id to poll, and a replay without a key would import the file twice.
- A replay with the same key and the same file answers
202with the original job, in whatever state it has now, and does not import again. - The same key with a different file is
409. - A key is scoped to the user and to uploads. The same key may also be used on a bulk import.
- A key is released only when the job succeeded, recorded activities and every one of them has since been deleted. The same file can then be uploaded again under that key. A job that failed, is still running or created no activities keeps its key.
Bulk import
POST /activities/bulk-import?source=generic takes a .zip archive in file. source is generic (the default, every supported activity file in the archive) or a provider export such as strava. POST /activities/bulk-import/folder?source=... imports the files that are in your own folder on the server instead, and removes them from the folder once they are safely staged.
Poll GET /jobs/{job_id} and read files_done and files_failed against files_total. A file that cannot be read counts as failed and does not stop the import.
409when you already have a bulk import running. One runs per user. The problem document carriesjob_id, the running import, and the response carriesContent-Locationnaming it, so a client that lost the202picks the import up again from there.400for an unknownsource, a name that is not.zip, an archive with no importable files, or an empty folder.
POST /activities/bulk-import also takes an Idempotency-Key header (up to 255 characters), with the same rules as the upload: a repeat with the same key, the same archive and the same source answers 202 with the original import, in whatever state it has now (including while it is the import that is running), and does not start another. The same key with a different archive or source is 409. A key is released only when its job record is removed. The folder import takes no key, because it has no request body to compare.
Provider refresh and range sync
POST /activities/refresh queues a sync of the last 24 hours from the providers you have linked. POST /garmin/activities and POST /strava/activities take start_date and end_date (query parameters) and queue a sync of that range. The range may not be longer than 366 days, may not end in the future and may not start after its end, or it is 400. A longer history is imported with several requests.
Provider links and syncs
Garmin Connect link. POST /garmin/link with the login starts the sign-in and answers 202 with a garmin_link job. Poll it. The status is running while it signs in, then succeeded or failed. While Garmin Connect wants a code the status stays running and mfa_required is true. A failed link carries error_code: invalid_credentials, incorrect_mfa, too_many_requests or internal. When mfa_required is true, send the code to POST /garmin/mfa (204) within 3 minutes and keep polling. POST /garmin/mfa is 409 when no login is waiting for a code. POST /garmin/link is 409 while an attempt is running.
Garmin Connect gear and health sync. POST /garmin/gear and POST /garmin/health (with start_date and end_date, at most 31 days) answer 202 with a garmin_sync_gear or garmin_sync_health job. A second request of the same kind while one is queued or running is 409.
Strava link, gear sync and unlink. POST /strava/link (the state, code and scope from the Strava callback), POST /strava/gear and POST /strava/unlink (with the caller's step-up) answer 202 with a strava_link, strava_gear or strava_unlink job. A second request of the same kind while one is queued or running is 409. A link whose granted scopes are too few is refused at once with 400 and urn:endurain:error:provider-scope-insufficient. Unlinking revokes the authorization with Strava and deletes the activities and gear imported from it. When the user withdraws Endurain's access on Strava instead, Endurain clears the tokens at the next sync and GET /profile carries two read-only fields until the user connects again or the data is deleted: strava_revoked_at, when Strava access ended, and strava_data_deletion_at, 7 days later, when the Strava-synced activities and gear are deleted. Both are null otherwise, and neither can be set by a client.
A provider that answers with a rate limit makes the job failed (gear and health syncs) or queued with retry_after set (activity refreshes). The routes that start a provider sync (/activities/refresh, /garmin/activities, /garmin/gear, /garmin/health, /strava/activities and /strava/gear) are limited to 6 requests per minute.
Profile export and import
Export. POST /profile/export takes the step-up body, {"step_up": {...}} (current_password, idp_reauth for an account without a password, and mfa_code when MFA is on) and answers 202 with a profile_export job. A succeeded export carries size_bytes and expires_at: fetch the ZIP with GET /profile/export/download before it expires (2 hours), from the same session that requested the export. A failed one carries error_code: timed_out or processing_failed. 409 while an export is running, 404 from the download when there is nothing finished to fetch for the calling session. A client that lost the job finds it with GET /jobs?kind=profile_export.
Import. POST /profile/import takes a .zip archive in file, validates and stages it, and answers 202 with a profile_import job. The status is running for the database part (one transaction: a failed import leaves nothing behind) and for the writing of the files that follows. A succeeded import carries imported, the number of items of each kind. A failed one carries error_code: invalid_file, too_large, too_many_activities, timed_out, wrong_account, older_version, files_incomplete or processing_failed. 409 while an import is running.
Bulk visibility edit
PATCH /activities with {"visibility": "public"|"followers"|"private"} changes the visibility of every activity you own and answers 202 with an activities_bulk_edit job. 409 while an edit is pending, and 400 when the body names no field to change. This route has no If-Match, because it addresses no single record.
Delete a user (administrators)
POST /users/{user_id}/delete needs users:write, the user's ETag in If-Match (see Errors, concurrency and rate limits) and the administrator's own step-up in the body's step_up object (current_password, or idp_reauth for an administrator without a password, and mfa_code when MFA is on). It signs the user out everywhere, deactivates the account and answers 202 with a user_deletion job, which then erases the data. Any administrator with users:read-all can read the job; it is kept for 2 hours. Until the account is gone, the administrator's user reads (GET /users and GET /users/{user_id}) carry deletion_requested_at, when the deletion was queued. It is null for an account that is not being deleted, and no client can set it.
409withurn:endurain:error:last-administratorwhen the user is the only administrator; make another user an administrator first. A409(urn:endurain:error:conflict) naming the running job when a deletion is already pending.403when an administrator targets their own account. UsePOST /profile/delete-accountfor that.403withurn:endurain:error:step-up-failed(or401idp-reauth-required) when the administrator's step-up does not verify; nothing is deleted.412and428as for any versioned write.- If the job fails, the account stays deactivated and signed out. Endurain queues the deletion again every hour, up to five times, and after that an administrator deletes the account again.
Delete your account
POST /profile/delete-account is confirmed with step-up in the body's step_up object (the current password, or a fresh identity-provider sign-in, and an MFA code when MFA is on; see Account security). It answers 202 with the user_deletion job ("status": "queued"), and it is fire and forget.
- The account is closed before the answer. Every session of the user ends, the account is deactivated, and the web client's refresh cookie is cleared on the response. The access token that made the request stops working too.
- There is nothing for the user to poll. The response has no
Content-Location: reading an account deletion needs an administrator scope, and the user can no longer sign in to call anything. A client should treat the202as final: sign the user out locally and show that the account is being deleted. - How long the erasure takes is not fixed. The data is removed in batches, so a large account takes longer. The job's record lives for 2 hours. There is no completion message.
- It cannot be undone. Export the profile first to keep a copy.
409withurn:endurain:error:last-administratorwhen the user is the only administrator, and a409(urn:endurain:error:conflict) when a deletion is already pending.403withurn:endurain:error:step-up-failedwhen the step-up does not verify (or401idp-reauth-requiredwhen an account without a password sends noidp_reauth); nothing is deleted.
Gear deletion
DELETE /gears/{gear_id} answers 202 with a gear_deletion job. The route checks that the gear is yours (404) and that If-Match names its current version (412, 428 without the header) before it queues anything. The job then unassigns the gear from the activities that carry it, a batch at a time, and deletes it, so a gear with a long history does not hold up the request. The gear stays readable until the job succeeded; read it again, or the activities, after that. A job that failed leaves the gear in place, so send the request again. 409 while a deletion of the same gear is queued or running. The status carries no fields beyond the shared ones.
Conflicts (409)
A start route answers 409 with urn:endurain:error:conflict while the same kind of work is already running for the user. The problem document carries the running job's id as job_id, and the response carries Content-Location naming it, so a client that lost the 202 of the first request picks the job up again from there:
- a bulk import, a profile export, a profile import, a bulk visibility edit, a gear deletion, a Garmin Connect link, a Garmin Connect gear or health sync, a Strava link, gear sync or unlink, an account deletion.
The same 409 code, with no job, also answers:
- an upload or a bulk import whose
Idempotency-Keywas used for a different request; - an upload while the user already has 10 uploads open (pending, processing or deferred);
POST /garmin/mfawhen no login waits for a code.
Do not retry a 409 straight away. Poll the running job until it reaches a final state, then start again if you still need to. An activity upload is limited differently: you can queue several, up to 10 open at once, and each gets its own job. An upload past that is 409 with no job to name. A refresh has no such limit.
Upload limits and formats
An attachment a record has one of (a profile photo, a user's photo, an identity provider's icon, the login page photo) is replaced with PUT on its path (/profile/photo, /users/{user_id}/photo, /identity-providers/{idp_id}/icon, /server-settings/login-photo), a multipart form with the image in file. The route answers 201 when there was nothing there before and 200 when it replaced an image; DELETE on the same path removes it.
Every upload route declares its body limit in the OpenAPI document as x-max-body-bytes: the largest file plus 1 MiB for the multipart framing. A body over the limit is 413 with urn:endurain:error:payload-too-large, refused before the route runs. A file of a type the route does not accept is 415 (urn:endurain:error:unsupported-format for an activity file, urn:endurain:error:unsupported-media-type for an image or media file); any other file the server cannot accept is 400. See Errors, concurrency and rate limits.
| Route | Accepts | Largest file |
|---|---|---|
POST /activities/upload |
.gpx, .fit, .tcx, or any of them gzipped (.gz) |
200 MiB |
POST /activities/bulk-import |
A .zip of activity files (the same extensions, and .fit.gz entries). source=strava reads a Strava export |
500 MiB |
POST /profile/import |
A .zip made by POST /profile/export |
500 MiB |
An archive may also hold at most 2 GiB once unpacked, and a bulk-import archive at most 2000 files of the same type (a profile archive at most 100000 entries). The upload routes in this table, and POST /activities/bulk-import/folder, are limited to 20 requests per minute. See Supported types for the activity types a file can map to.
Realtime hint
A client that holds a WebSocket can learn that a job changed without waiting for its next poll. The server sends {"message": "JOB_STATUS_CHANGED", "job_id": "<id>", "kind": "<kind>"} to the user who started the job. The hint is best effort and carries no status: read the job at GET /jobs/{job_id}. It is sent each time a job reaches a final state, succeeded or failed, and also when a garmin_link job starts waiting for an MFA code.
An activity refresh waiting for a rate limit sends no hint until it ends. A job that the server closes because it stopped making progress (an ingestion job idle for a day) and an account deletion send no hint, so keep polling them. A finished Garmin Connect or Strava gear sync also sends GEARS_CHANGED, and a Garmin Connect health sync HEALTH_CHANGED, which mean "fetch that data again" and do not name a job.