JSON:API documents and media types

The JSON:API transport at /api/json/v1 covers configuration and observability. It follows JSON:API 1.0 document conventions and exposes only reviewed resource actions and public fields. Warehouse fact rows belong to GraphQL, and inbound deliveries belong to webhook ingestion.

Request headers

Every JSON:API request sends:

Accept: application/vnd.api+json
Authorization: Bearer <token>

Requests with a body also send:

Content-Type: application/vnd.api+json

Safe methods require api_read; unsafe create and update operations require api_write. The API reference displays the exact scope for each operation. Unsafe requests should also carry a unique Idempotency-Key so a retry cannot repeat a completed effect.

Resource documents

A single-resource response has one data object:

{
  "data": {
    "type": "workflow",
    "id": "00000000-0000-4000-8000-000000000001",
    "attributes": {
      "name": "Order intake",
      "is_active": true
    }
  },
  "jsonapi": { "version": "1.0" }
}

Treat the pair of type and id as the resource identity. Attributes are resource-specific and may be nullable. Only fields shown in the reference are public; internal secrets, hashes, raw payloads, share tokens, and unreviewed actions remain unavailable.

A collection response has a data array. An empty array is a successful result, not an error:

{
  "data": [],
  "jsonapi": { "version": "1.0" },
  "links": {
    "self": "https://hodoflow.com/api/json/v1/workflows?page[limit]=10",
    "next": null,
    "prev": null
  }
}

Always pass an explicit limit when an operation accepts pagination. Pagination support and defaults are operation-specific; Hodoflow does not promise one global default for every generated collection.

Write documents

Write the resource type and supported attributes inside data:

{
  "data": {
    "type": "dashboard",
    "attributes": {
      "name": "Fulfillment health",
      "description": "Operational delivery metrics"
    }
  }
}

Do not copy fields from a read response into a write blindly. IDs, derived values, organization/workspace context, timestamps, and read-only attributes may be server-controlled. Inspect the operation's request-body fields in the reference.

Relationships, includes, and sparse fields

Where an operation declares support:

• include=relationship.path asks the response to sideload related resources;
• fields[type]=field_a,field_b limits attributes for one resource type; and
• relationship linkage appears under a resource object's relationships map.

Request only what the client consumes. An empty allowed-include pattern means that operation exposes no relationship include, even if the internal resource has relationships.

Response headers

Successful and failed JSON:API responses expose:

• x-api-version: v1 — the path-versioned JSON:API contract;
• x-request-id — the correlation ID to retain for logs and support;
• Retry-After on rate limits and some transient failures; and
• idempotency-replayed: true when a completed unsafe response is replayed.

Continue with Pagination, filtering, and sorting, Errors and request IDs, and Idempotency and retries.