Reporting API

Overview

• Base URL: https://api.ottotasks.dev.carbonai.ca/v1
• Every endpoint is GET only. The API cannot change any data.
• Each credential belongs to one company. You only ever see that company's data; there is no company parameter.
• Machine-readable reference (OpenAPI): https://api.ottotasks.dev.carbonai.ca/docs/openapi.json

Authentication

CarbonAi gives you a client ID and a client secret. Exchange them for an access token using the OAuth 2.0 client credentials grant:

POST https://api.ottotasks.dev.carbonai.ca/connect/token
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET

curl -s https://api.ottotasks.dev.carbonai.ca/connect/token \
  -d grant_type=client_credentials \
  --data-urlencode "client_id=$CLIENT_ID" \
  --data-urlencode "client_secret=$CLIENT_SECRET"

The response contains access_token, token_type (Bearer) and expires_in (seconds):

{ "access_token": "…", "expires_in": 3600, "token_type": "Bearer", "scope": "…" }

Send the token on every API request:

curl -s "https://api.ottotasks.dev.carbonai.ca/v1/campaigns" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

• Tokens last about one hour. Request a new token at the start of each run rather than storing one.
• Send the client secret only in the form body of the token request. Never put it in a URL or query string.

Paging

Every endpoint returns one page at a time.

Every response has the same envelope:

{
  "items": [ … ],
  "pageSize": 500,
  "hasMore": true,
  "nextAfter": "0b1f6c55-3f0e-4d55-9c1a-3c3f2a9d7e01"
}

Keep requesting with after set to the last nextAfter until hasMore is false. nextAfter is null on the last page. There is no total count.

• pageSize in the response is the size actually used (after the 1000 limit).
• Rows are returned in a stable order (by id), and each page starts after the previous one's last id, so rows created or deleted while you page never cause a row to repeat or be skipped.
• task-values, task-exceptions and asset-values page over tasks and assets, not rows. A page holds every row for up to pageSize tasks (or assets), so one task's or asset's rows never split across two pages. These pages can contain more than pageSize rows.
• Stop when hasMore is false, not when a page is empty. On those three endpoints, a page is only empty while hasMore is true if a very long run of tasks or assets has no rows.

GET https://api.ottotasks.dev.carbonai.ca/v1/tasks?pageSize=1000                    → "hasMore": true,  "nextAfter": "0b1f…"
GET https://api.ottotasks.dev.carbonai.ca/v1/tasks?pageSize=1000&after=0b1f…      → "hasMore": true,  "nextAfter": "7c42…"
GET https://api.ottotasks.dev.carbonai.ca/v1/tasks?pageSize=1000&after=7c42…      → "hasMore": false, "nextAfter": null  (stop)

Conventions

• Column names are camelCase.
• Ids are UUID strings.
• Enums are strings, for example "Completed", not numbers.
• Date-times are UTC in ISO 8601 with a Z suffix, for example 2026-11-05T17:44:30Z. Fractional seconds may appear.
• Calendar dates have no time or zone, for example 2026-11-05. Don't convert them to a time zone.
• A value that isn't set is null. Coordinates are null when the position is unknown (missing, unreadable, or 0,0).
• Date filters such as completedSince take an ISO 8601 date-time and must be URL-encoded. Use UTC with a Z suffix, for example completedSince=2026-11-01T00:00:00Z. A value with no offset, or a date alone (2026-11-01), is read as UTC. If you send an offset instead, encode the plus sign as %2B (2026-11-01T00:00:00%2B02:00): a raw + in a query string is read as a space, and the date is rejected with 400.

Endpoints

All endpoints accept pageSize and after. Other filters are listed per endpoint and are all optional.

How the tables join

A task's campaignId, assetId and locationId can be null, so join tasks to the other tables as optional (left) joins.

Limits and errors

• Rate limit: API calls (/v1/…): 60 requests per minute per client, in total across all endpoints. Token requests (/connect/token): 30 per minute per IP address. Each IP address also has limits that normal use won't reach: 300 /v1/… requests per minute before the token is checked (shared by every client calling from that address), 60 per minute for /v1/… calls without a valid token, and 60 per minute for /docs/openapi.json. Over the limit you get 429 with a Retry-After header in whole seconds. Wait that long, then retry.
• Page size: at most 1000 per request.
• Refresh: pull the data at most once a day. The API returns the full data set each time; there is no "changed since" sync.
• completedSince: tasks can change after they are completed (for example, an office review raises exceptions later), so completedSince is a convenience filter, not a key for incremental refresh. Pulling only recently completed tasks will miss those later changes.

Versioning

The /v1 contract is fixed: new columns may be added to a table, so ignore columns you don't recognise. Columns will not be renamed or removed in /v1; changes like that only happen in a new version (/v2).

Credentials and rotation

• Client IDs and secrets are issued by CarbonAi. Each secret is valid for 365 days.
• Client IDs start with ottotasks-, for example ottotasks-acme.
• Ask CarbonAi for a new secret about a month before the current one expires. The new secret works with the same client ID, so you only replace the secret in your configuration.
• Keep the secret private: store it in a secrets store, not in code, shared files, emails or URLs. If you think it has been exposed, contact CarbonAi so it can be revoked and replaced.