Appearance
API conventions #
Request conventions #
- Content-Type:
application/jsonfor requests with a body - Auth header:
Authorization: ApiKey <key>on every authenticated request - Tenancy: include
org_hashordevice_hashin 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.
Developer inventory pagination #
GET /api/developer/devices/ returns a JSON array with pagination headers, not the organisation inventory envelope above. Follow X-Next-Cursor using cursor while X-Has-More is 1. limit is capped at 500. Setting include_counts=0 omits exact totals; use X-Fleet-Has-Devices for the unfiltered empty-fleet check.
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 |
429 | Rate limited | Respect Retry-After before retrying |
5xx | Server error | Retry with bounded backoff; avoid replaying non-idempotent writes blindly |
Treat validation and permission failures as caller issues. Rate limits need delayed retries. A server error does not prove that a write had no effect; check state before replaying it.
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_hashanddevice_hashpersisted 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.