REST API Reference

Complete reference for the IDI Fly v3 Integration REST API. All paths are relative to the REST base URL https://api.idi-fly.com (see Base URLs).

Unless stated otherwise, every endpoint:

• Requires an Authorization: Bearer <token> header (see Authentication).
• Is scoped to your organisation — you only ever see your own resources.
• Returns application/json.

---

Authentication

POST /v3/auth/token

Exchange client credentials for a JWT access token. This is the only endpoint that uses an API key instead of a bearer token.

Headers

x-api-key: <your-api-key>
Content-Type: application/json

Body

Field	Type	Required	Description
grant_type	string	✅	Must be client_credentials
client_id	string	✅	Cognito App Client ID
client_secret	string	✅	Cognito App Client secret

Response 200 OK

{
  "access_token": "eyJraWQiOiJEaWVoK0U0...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Errors

Status	error	When
400	invalid_request	Missing body, client_id, or client_secret
400	unsupported_grant_type	grant_type is not client_credentials
401	invalid_client	Credentials rejected by Cognito

---

Jobs

A job is a drone mission request. Jobs progress through a defined status lifecycle.

Method	Path	Scope	Description
POST	/v3/jobs/create	command:create	Create a job
GET	/v3/jobs	command:read	List jobs
GET	/v3/jobs/{jobId}	command:read	Get a job
PATCH	/v3/jobs/{jobId}	command:update	Update a job
DELETE	/v3/jobs/{jobId}	command:update	Delete a job
POST	/v3/jobs/{jobId}/cancel	command:update	Cancel a pending/queued job

Job status lifecycle

Create a job

POST /v3/jobs/create

Field	Type	Required	Description
name	string	✅	Human-readable job name
missionId	string	✅	Mission to run
deviceId	string	✅	Target drone device ID
deviceGroupId	string	✅	Device group the drone belongs to
description	string	—	Optional description
priority	integer	—	Priority (default 5)
scheduledAt	string (ISO 8601)	—	When to run the job
metadata	object	—	Free-form key/value data

curl -X POST https://api.idi-fly.com/v3/jobs/create \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Inspection Mission Alpha",
    "description": "Routine infrastructure inspection",
    "missionId": "mission-uuid-123",
    "deviceId": "drone-uuid-456",
    "deviceGroupId": "group-uuid-789",
    "priority": 5,
    "scheduledAt": "2024-01-15T10:00:00Z",
    "metadata": { "customer": "ACME Corp" }
  }'

Response 201 Created

{
  "success": true,
  "job": {
    "jobId": "job-uuid-abc",
    "name": "Inspection Mission Alpha",
    "status": "PENDING",
    "priority": 5,
    "createdAt": "2024-01-14T15:30:00Z"
  }
}

List jobs

GET /v3/jobs

Query param	Type	Description
status	string	Filter by status (PENDING, QUEUED, IN_PROGRESS, COMPLETED, FAILED, CANCELLED)
limit	integer	Max results, default 50, capped at 100

curl -X GET "https://api.idi-fly.com/v3/jobs?status=PENDING&limit=20" \
  -H "Authorization: Bearer <token>"

Response 200 OK

{
  "success": true,
  "jobs": [ { "jobId": "job-uuid-abc", "status": "PENDING" } ],
  "count": 1
}

If more results are available, a nextToken field is returned; pass it back to paginate.

Get a job

GET /v3/jobs/{jobId} → 200 OK with { "success": true, "job": { ... } }, or 404 if not found.

Update a job

PATCH /v3/jobs/{jobId} — all fields optional.

Field	Type	Description
name	string	New name
description	string	New description
priority	integer	New priority
status	string	New status
metadata	object	Replacement metadata

Cancel a job

POST /v3/jobs/{jobId}/cancel — cancels a PENDING or QUEUED job. Returns 400 if the job is in a state that cannot be cancelled, 404 if it does not exist.

Delete a job

DELETE /v3/jobs/{jobId} → 200 OK with { "success": true, "message": "Job deleted successfully" }.

---

Streams

Generate shareable links for a device's live stream or telemetry.

Method	Path	Scope	Description
POST	/v3/streams/share	stream:share	Create a stream share
GET	/v3/streams/share	share:read	List active stream shares
GET	/v3/streams/share/{shareCode}	share:read	Get a stream share
DELETE	/v3/streams/share/{shareCode}	share:manage	Revoke a stream share

Create a stream share

POST /v3/streams/share

Field	Type	Required	Description
resourceId	string	✅	Device or stream ID to share
shareType	string	✅	STREAM (live video) or DEVICE_STATUS (telemetry)
permissions	array	—	Defaults to ["view"]; also supports "control"
expiresIn	integer	—	Seconds until expiry (default 3600, max 86400)
maxViewers	integer	—	Maximum concurrent viewers (default 10)
metadata	object	—	Free-form data

curl -X POST https://api.idi-fly.com/v3/streams/share \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "resourceId": "device-uuid-123",
    "shareType": "STREAM",
    "permissions": ["view"],
    "expiresIn": 3600,
    "maxViewers": 10
  }'

Response 201 Created

{
  "success": true,
  "share": {
    "shareCode": "abc123xyz",
    "shareUrl": "https://app.idi-fly.com/share/abc123xyz",
    "expiresAt": "2024-01-14T16:30:00Z",
    "maxViewers": 10
  }
}

---

Shares

Manage all shares (both STREAM and DEVICE_STATUS) belonging to your organisation.

Method	Path	Scope	Description
GET	/v3/shares	share:read	List active shares
GET	/v3/shares/{shareCode}	share:read	Get share details
DELETE	/v3/shares/{shareCode}	share:manage	Revoke a share

List shares

curl -X GET https://api.idi-fly.com/v3/shares \
  -H "Authorization: Bearer <token>"

Response 200 OK

{
  "success": true,
  "shares": [
    {
      "shareCode": "abc123xyz",
      "resourceId": "device-uuid",
      "shareType": "STREAM",
      "permissions": ["view"],
      "expiresAt": "2024-01-15T12:00:00Z",
      "maxViewers": 10,
      "currentViewers": 3
    }
  ],
  "count": 1
}

Requesting a share that belongs to a different organisation returns 403; an unknown or expired share returns 404.

---

Resources

Method	Path	Scope	Description
GET	/v3/resources	resources:read	List device groups available to your organisation

curl -X GET https://api.idi-fly.com/v3/resources \
  -H "Authorization: Bearer <token>"

Response 200 OK

{
  "success": true,
  "resources": [
    {
      "deviceGroupId": "group-uuid-123",
      "name": "Fleet Alpha",
      "description": "Primary inspection fleet",
      "deviceCount": 5,
      "devices": [
        { "deviceId": "drone-001", "name": "Mavic 3 Enterprise", "status": "online" }
      ]
    }
  ],
  "count": 1
}

---

Errors

All endpoints share the same status-code semantics:

Status	Meaning
400	Missing or invalid parameters
401	Missing, invalid, or expired token
403	Lacking the required scope, or accessing another organisation's resource
404	Resource not found
405	Method not allowed for that route
500	Internal server error

Resource errors return { "error": "<message>" }. The token endpoint returns the OAuth shape { "error": "<code>", "error_description": "<message>" }.

---

Rate limits

Endpoint	Rate limit	Burst
POST /v3/auth/token	50 / second	100
All other endpoints	No fixed limit	—

Cache and reuse your access token for its full lifetime rather than requesting a new one per call.