API reference

{
  "additionalProperties": false,
  "description": "One page of results (FR-API-003, FR-API-025).\n\n`credits_consumed` is on every response, not only on a quota error. Opaque consumption destroys developer trust faster than a restrictive limit does, so the cost of a call is reported at the moment the call is made.",
  "properties": {
    "credits_consumed": {
      "minimum": 0,
      "type": "number"
    },
    "data": {
      "items": {
        "type": "object"
      },
      "type": "array"
    },
    "dataset_version": {
      "description": "The version actually read, so a dynamic subset's staleness is visible.",
      "type": [
        "string",
        "null"
      ]
    },
    "next_cursor": {
      "description": "Absent when this is the last page. Opaque.",
      "type": [
        "string",
        "null"
      ]
    },
    "total": {
      "description": "Absent unless the caller asked for it: an exact count is a second scan, and most callers do not need one.",
      "minimum": 0,
      "type": [
        "integer",
        "null"
      ]
    }
  },
  "required": [
    "data",
    "credits_consumed"
  ],
  "title": "Page",
  "type": "object"
}

{
  "additionalProperties": false,
  "description": "The one error shape every AkilIQ surface returns.\n\n`code` is stable and machine-readable, never a bare string, so an integrator can branch on it without parsing prose. `correlation_id` is present on every error, so a user reporting a problem quotes something that maps to a trace (NFR-OBS-003, FR-ADM-006).\n\nNo error message carries a secret, a DSN, a stack trace or a database identifier.",
  "properties": {
    "code": {
      "examples": [
        "quota_exceeded",
        "rate_limited",
        "field_not_filterable",
        "not_found"
      ],
      "pattern": "^[a-z][a-z0-9_]*$",
      "type": "string"
    },
    "correlation_id": {
      "pattern": "^cor_[0-9a-f]{32}$",
      "type": "string"
    },
    "details": {
      "description": "Structured specifics — which field, which operator, which limit — so a client can act without parsing the message.",
      "type": "object"
    },
    "documentation_url": {
      "format": "uri",
      "type": "string"
    },
    "message": {
      "description": "Human-readable, and safe to show a caller.",
      "minLength": 1,
      "type": "string"
    }
  },
  "required": [
    "code",
    "message",
    "correlation_id"
  ],
  "title": "Error",
  "type": "object"
}

{
  "additionalProperties": false,
  "properties": {
    "code": {
      "enum": [
        "unknown_field",
        "field_not_returnable",
        "field_not_filterable",
        "field_not_sortable",
        "field_not_searchable",
        "operator_not_permitted",
        "value_required",
        "value_not_permitted",
        "value_must_be_list",
        "value_must_not_be_list",
        "limit_exceeded",
        "search_not_supported",
        "dataset_mismatch",
        "value_type_mismatch",
        "limit_invalid",
        "offset_invalid",
        "offset_exceeded",
        "pagination_conflict",
        "cursor_invalid",
        "sort_direction_invalid",
        "cost_exceeded"
      ],
      "type": "string"
    },
    "field": {
      "type": "string"
    },
    "message": {
      "type": "string"
    }
  },
  "required": [
    "code",
    "message"
  ],
  "type": "object"
}

{
  "additionalProperties": false,
  "description": "The one internal representation every read surface compiles to (FR-API-001).\n\nREST today, GraphQL later, internal consumers throughout — all of them produce this. Authorisation, field permissions and limits are applied once, to this specification, never per surface. That is what makes a second surface additive rather than a second place to get permissions wrong.",
  "properties": {
    "cursor": {
      "description": "An opaque continuation token (FR-API-003). Opaque on purpose: a caller that can construct one can page outside the ordering the descriptor guarantees.\n\nWithin the specification it is the unpadded base64url encoding of `{\"after\": [...], \"order\": [[field, direction], ...]}` — the key values of the last row returned, and the order they were read in. A surface that hands cursors to callers seals that payload and opens it before building a specification.",
      "type": "string"
    },
    "dataset": {
      "description": "May be left out: the path names the dataset. If given, it must be the path's.",
      "pattern": "^ds_[0-9A-HJKMNP-TV-Z]{26}$",
      "type": "string"
    },
    "filters": {
      "items": {
        "$ref": "#/components/schemas/QuerySpecificationFilter"
      },
      "type": "array"
    },
    "limit": {
      "minimum": 1,
      "type": "integer"
    },
    "offset": {
      "description": "Offset pagination (FR-API-003). Available but capped, because deep offsets scan what they skip.",
      "minimum": 0,
      "type": "integer"
    },
    "search": {
      "additionalProperties": false,
      "properties": {
        "fields": {
          "items": {
            "$ref": "#/components/schemas/QuerySpecificationIdentifier"
          },
          "type": "array",
          "uniqueItems": true
        },
        "query": {
          "maxLength": 512,
          "minLength": 1,
          "type": "string"
        }
      },
      "required": [
        "query"
      ],
      "type": "object"
    },
    "select": {
      "description": "Field projection (FR-API-004). Intersected against the descriptor's returnable set; omitted means every returnable field.",
      "items": {
        "$ref": "#/components/schemas/QuerySpecificationIdentifier"
      },
      "type": "array",
      "uniqueItems": true
    },
    "sort": {
      "description": "Sorting, on publisher-permitted fields only (FR-API-005).",
      "items": {
        "$ref": "#/components/schemas/QuerySpecificationSort"
      },
      "type": "array"
    },
    "version": {
      "default": "latest",
      "description": "A dataset version, or `latest`. A dynamic subset resolves this at read time and reports what it resolved against, so staleness is never ambiguous (FR-FLOW-013).",
      "type": "string"
    }
  },
  "title": "Query Specification",
  "type": "object"
}