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:

{
  "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.

Related

• Authentication
• Gateway API overview