API conventions #

Request conventions #

Content-Type: application/json for requests with a body
Auth header: Authorization: ApiKey <key> on every authenticated request
Tenancy: include org_hash or device_hash in the path - do not assume a default organisation

Pagination #

List endpoints (e.g. /api/organisations/{org_hash}/devices/) return paginated results:

json

{
  "count": 250,
  "next": "https://gateway.dataplicity.com/...?offset=100&limit=100",
  "previous": null,
  "results": []
}

Param	Purpose
`limit`	Page size
`offset`	Start index

Iterate until next is null. Do not assume all devices fit in one page.

Error handling #

Status	Meaning	Action
`400`	Validation error	Fix request payload or parameters
`401`	Authentication failed	Check API key format and value
`403`	Forbidden / insufficient scope	Check key scopes and tenancy
`404`	Resource not found	Verify `org_hash` / `device_hash`
`5xx`	Server error	Retry with exponential backoff

Treat 4xx as caller issues. Treat 5xx as transient - retry with a bounded backoff budget.

Idempotency #

Write operations (device PATCH, incident rule creation, status refresh POST) are not guaranteed idempotent unless documented otherwise. Use client-side deduplication or idempotency keys in your integration layer for workflow-triggering actions.

Production checklist #

[ ] API keys in server-side secret storage only
[ ] Separate keys per environment
[ ] Request timeouts configured (e.g. 30s)
[ ] Retry with exponential backoff for 5xx
[ ] org_hash and device_hash persisted as stable foreign keys
[ ] Read-only integration tested before enabling writes
[ ] Alerting on repeated auth failures
[ ] Key rotation schedule documented

Interactive reference #

The live OpenAPI schema is the source of truth for field-level details:

Docs UI: gateway.dataplicity.com
Schema: gateway.dataplicity.com/developers/schema/

When this documentation and the schema differ, prefer the schema.