{"components":{"headers":{"Deprecation":{"description":"When this operation was deprecated, as @ and Unix seconds.","schema":{"pattern":"^@[0-9]+$","type":"string"}},"ETag":{"description":"The page's strong entity tag; send it back in If-None-Match.","schema":{"pattern":"^\"[^\"]+\"$","type":"string"}},"Link":{"description":"Where the deprecation notice is published.","schema":{"type":"string"}},"Retry-After":{"description":"Seconds to wait before the next request would be served.","schema":{"minimum":1,"type":"integer"}},"Sunset":{"description":"The first day this operation may no longer be served.","schema":{"type":"string"}},"WWW-Authenticate":{"description":"The authentication scheme the data API expects.","schema":{"type":"string"}},"X-Correlation-ID":{"description":"The correlation ID of this request; quote it when reporting a problem.","schema":{"pattern":"^cor_[0-9a-f]{32}$","type":"string"}},"X-Credits-Consumed":{"description":"The credits this request consumed, by the published formula.","schema":{"minimum":0,"type":"number"}},"X-Quota-Limit":{"description":"The credits of the binding quota for the period.","schema":{"minimum":0,"type":"number"}},"X-Quota-Period":{"description":"The quota period: hour, day or month.","schema":{"enum":["hour","day","month"],"type":"string"}},"X-Quota-Remaining":{"description":"The credits of that quota left after this request.","schema":{"minimum":0,"type":"number"}},"X-Quota-Reset":{"description":"Seconds until the quota period ends.","schema":{"minimum":0,"type":"integer"}},"X-RateLimit-Limit":{"description":"The burst of the rate-limit bucket that binds this request.","schema":{"minimum":0,"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in that bucket after this one.","schema":{"minimum":0,"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until that bucket is full again.","schema":{"minimum":0,"type":"integer"}},"X-Request-ID":{"description":"The ID this request's metering event is recorded under.","schema":{"pattern":"^req_[0-9A-HJKMNP-TV-Z]{26}$","type":"string"}}},"schemas":{"Error":{"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"},"Page":{"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"},"QuerySpecification":{"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"},"QuerySpecificationFilter":{"additionalProperties":false,"allOf":[{"description":"is_null and is_not_null take no value; every other operator requires one.","else":{"required":["value"]},"if":{"properties":{"operator":{"enum":["is_null","is_not_null"]}},"required":["operator"]},"then":{"not":{"required":["value"]}}},{"description":"in and not_in take an array; every other operator refuses one. Without the else branch, `eq` with a list would be schema-valid and only the structural validator would catch it — two gates disagreeing about the same rule.","else":{"properties":{"value":{"not":{"type":"array"}}}},"if":{"properties":{"operator":{"enum":["in","not_in"]}},"required":["operator"]},"then":{"properties":{"value":{"minItems":1,"type":"array"}}}}],"properties":{"field":{"$ref":"#/components/schemas/QuerySpecificationIdentifier"},"operator":{"$ref":"#/components/schemas/QuerySpecificationOperator"},"value":{"$ref":"#/components/schemas/QuerySpecificationValue"}},"required":["field","operator"],"type":"object"},"QuerySpecificationIdentifier":{"maxLength":63,"minLength":1,"pattern":"^[a-z_][a-z0-9_]*$","type":"string"},"QuerySpecificationOperator":{"enum":["eq","neq","gt","gte","lt","lte","contains","starts_with","ends_with","in","not_in","is_null","is_not_null","matches"],"type":"string"},"QuerySpecificationSort":{"additionalProperties":false,"properties":{"direction":{"default":"asc","enum":["asc","desc"],"type":"string"},"field":{"$ref":"#/components/schemas/QuerySpecificationIdentifier"}},"required":["field"],"type":"object"},"QuerySpecificationValue":{"description":"A bound parameter. Never interpolated into a statement, in any form, for any reason.\n\nIts JSON type must suit the field's type: a string for string, text, enum, uri and email; an integer literal for integer; a number for decimal; a boolean for boolean; `YYYY-MM-DD` for date; `YYYY-MM-DDTHH:MM:SS[.ffffff]` for datetime; the same with `Z` or an offset for timestamptz. A date or timestamptz may instead be relative to the time of the request (FR-API-002): `now`, or `now` plus or minus a count of minutes (`m`), hours (`h`), days (`d`) or weeks (`w`) — `now-7d`. It resolves in UTC, to the second. A date range is two clauses on one field, `gte` and `lt`: filters combine with AND.","items":{"type":["string","number","boolean"]},"type":["string","number","boolean","null","array"]},"Rejection":{"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"}},"securitySchemes":{"ApiKey":{"bearerFormat":"akq_live_… or akq_test_…","description":"An API key issued on the API page: live keys read your organisation's datasets, sandbox keys the sample dataset.","scheme":"bearer","type":"http"}}},"info":{"description":"Generated from the data API's implementation by `make codegen`; do not edit by hand.","summary":"Read published datasets with an API key.","title":"AkilIQ data API","version":"v1"},"jsonSchemaDialect":"https://json-schema.org/draft/2020-12/schema","openapi":"3.1.0","paths":{"/v1/datasets/{dataset_id}/query":{"post":{"description":"For a specification too long for a URL; it answers exactly as the rows endpoint does.","operationId":"queryRows","parameters":[{"description":"The published dataset's ID.","in":"path","name":"dataset_id","required":true,"schema":{"pattern":"^ds_[0-9A-HJKMNP-TV-Z]{26}$","type":"string"}},{"description":"The ETag of a page already held.","in":"header","name":"If-None-Match","required":false,"schema":{"type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuerySpecification"}}},"description":"The Query Specification, at most 64 KiB.","required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page"}}},"description":"A page of rows.","headers":{"ETag":{"description":"The page's strong entity tag; send it back in If-None-Match.","required":true,"schema":{"pattern":"^\"[^\"]+\"$","type":"string"}},"X-Correlation-ID":{"description":"The correlation ID of this request; quote it when reporting a problem.","required":true,"schema":{"pattern":"^cor_[0-9a-f]{32}$","type":"string"}},"X-Credits-Consumed":{"description":"The credits this request consumed, by the published formula.","required":true,"schema":{"minimum":0,"type":"number"}},"X-Quota-Limit":{"description":"The credits of the binding quota for the period.","required":false,"schema":{"minimum":0,"type":"number"}},"X-Quota-Period":{"description":"The quota period: hour, day or month.","required":false,"schema":{"enum":["hour","day","month"],"type":"string"}},"X-Quota-Remaining":{"description":"The credits of that quota left after this request.","required":false,"schema":{"minimum":0,"type":"number"}},"X-Quota-Reset":{"description":"Seconds until the quota period ends.","required":false,"schema":{"minimum":0,"type":"integer"}},"X-RateLimit-Limit":{"description":"The burst of the rate-limit bucket that binds this request.","required":false,"schema":{"minimum":0,"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in that bucket after this one.","required":false,"schema":{"minimum":0,"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until that bucket is full again.","required":false,"schema":{"minimum":0,"type":"integer"}},"X-Request-ID":{"description":"The ID this request's metering event is recorded under.","required":false,"schema":{"pattern":"^req_[0-9A-HJKMNP-TV-Z]{26}$","type":"string"}}}},"400":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"properties":{"code":{"enum":["query_invalid","query_malformed"]}}},{"if":{"properties":{"code":{"const":"query_invalid"}},"required":["code"]},"then":{"properties":{"details":{"properties":{"rejections":{"items":{"$ref":"#/components/schemas/Rejection"},"minItems":1,"type":"array"}},"required":["rejections"],"type":"object"}},"required":["details"]}}]}}},"description":"The dataset's descriptor refuses the query; details.rejections lists every reason. The Query Specification cannot be read: not a JSON object, another query parameter, or larger than 64 KiB.","headers":{"X-Correlation-ID":{"description":"The correlation ID of this request; quote it when reporting a problem.","required":true,"schema":{"pattern":"^cor_[0-9a-f]{32}$","type":"string"}},"X-Credits-Consumed":{"description":"The credits this request consumed, by the published formula.","required":false,"schema":{"minimum":0,"type":"number"}},"X-RateLimit-Limit":{"description":"The burst of the rate-limit bucket that binds this request.","required":false,"schema":{"minimum":0,"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in that bucket after this one.","required":false,"schema":{"minimum":0,"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until that bucket is full again.","required":false,"schema":{"minimum":0,"type":"integer"}},"X-Request-ID":{"description":"The ID this request's metering event is recorded under.","required":false,"schema":{"pattern":"^req_[0-9A-HJKMNP-TV-Z]{26}$","type":"string"}}}},"401":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"properties":{"code":{"enum":["unauthenticated"]}}}]}}},"description":"No API key, or one that is unknown, revoked, expired or of a deactivated organisation.","headers":{"WWW-Authenticate":{"description":"The authentication scheme the data API expects.","required":true,"schema":{"type":"string"}},"X-Correlation-ID":{"description":"The correlation ID of this request; quote it when reporting a problem.","required":true,"schema":{"pattern":"^cor_[0-9a-f]{32}$","type":"string"}}}},"403":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"properties":{"code":{"enum":["operation_not_permitted"]}}},{"if":{"properties":{"code":{"const":"operation_not_permitted"}},"required":["code"]},"then":{"properties":{"details":{"properties":{"operation":{"enum":["rows","query"],"type":"string"}},"type":"object"}},"required":["details"]}}]}}},"description":"The API key is not scoped to this operation.","headers":{"X-Correlation-ID":{"description":"The correlation ID of this request; quote it when reporting a problem.","required":true,"schema":{"pattern":"^cor_[0-9a-f]{32}$","type":"string"}},"X-Credits-Consumed":{"description":"The credits this request consumed, by the published formula.","required":false,"schema":{"minimum":0,"type":"number"}},"X-RateLimit-Limit":{"description":"The burst of the rate-limit bucket that binds this request.","required":false,"schema":{"minimum":0,"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in that bucket after this one.","required":false,"schema":{"minimum":0,"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until that bucket is full again.","required":false,"schema":{"minimum":0,"type":"integer"}},"X-Request-ID":{"description":"The ID this request's metering event is recorded under.","required":false,"schema":{"pattern":"^req_[0-9A-HJKMNP-TV-Z]{26}$","type":"string"}}}},"404":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"properties":{"code":{"enum":["not_found"]}}}]}}},"description":"No such dataset, not published, or outside the key's datasets: one answer for all three.","headers":{"X-Correlation-ID":{"description":"The correlation ID of this request; quote it when reporting a problem.","required":true,"schema":{"pattern":"^cor_[0-9a-f]{32}$","type":"string"}},"X-Credits-Consumed":{"description":"The credits this request consumed, by the published formula.","required":false,"schema":{"minimum":0,"type":"number"}},"X-RateLimit-Limit":{"description":"The burst of the rate-limit bucket that binds this request.","required":false,"schema":{"minimum":0,"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in that bucket after this one.","required":false,"schema":{"minimum":0,"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until that bucket is full again.","required":false,"schema":{"minimum":0,"type":"integer"}},"X-Request-ID":{"description":"The ID this request's metering event is recorded under.","required":false,"schema":{"pattern":"^req_[0-9A-HJKMNP-TV-Z]{26}$","type":"string"}}}},"412":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"properties":{"code":{"enum":["precondition_failed"]}}}]}}},"description":"A POST whose If-None-Match matched the current representation.","headers":{"X-Correlation-ID":{"description":"The correlation ID of this request; quote it when reporting a problem.","required":true,"schema":{"pattern":"^cor_[0-9a-f]{32}$","type":"string"}},"X-Credits-Consumed":{"description":"The credits this request consumed, by the published formula.","required":false,"schema":{"minimum":0,"type":"number"}},"X-RateLimit-Limit":{"description":"The burst of the rate-limit bucket that binds this request.","required":false,"schema":{"minimum":0,"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in that bucket after this one.","required":false,"schema":{"minimum":0,"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until that bucket is full again.","required":false,"schema":{"minimum":0,"type":"integer"}},"X-Request-ID":{"description":"The ID this request's metering event is recorded under.","required":false,"schema":{"pattern":"^req_[0-9A-HJKMNP-TV-Z]{26}$","type":"string"}}}},"413":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"properties":{"code":{"enum":["query_malformed"]}}}]}}},"description":"The Query Specification cannot be read: not a JSON object, another query parameter, or larger than 64 KiB.","headers":{"X-Correlation-ID":{"description":"The correlation ID of this request; quote it when reporting a problem.","required":true,"schema":{"pattern":"^cor_[0-9a-f]{32}$","type":"string"}},"X-Credits-Consumed":{"description":"The credits this request consumed, by the published formula.","required":false,"schema":{"minimum":0,"type":"number"}},"X-RateLimit-Limit":{"description":"The burst of the rate-limit bucket that binds this request.","required":false,"schema":{"minimum":0,"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in that bucket after this one.","required":false,"schema":{"minimum":0,"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until that bucket is full again.","required":false,"schema":{"minimum":0,"type":"integer"}},"X-Request-ID":{"description":"The ID this request's metering event is recorded under.","required":false,"schema":{"pattern":"^req_[0-9A-HJKMNP-TV-Z]{26}$","type":"string"}}}},"429":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"properties":{"code":{"enum":["rate_limited","quota_exceeded"]}}},{"if":{"properties":{"code":{"const":"rate_limited"}},"required":["code"]},"then":{"properties":{"details":{"properties":{"retry_after_seconds":{"minimum":1,"type":"integer"}},"required":["retry_after_seconds"],"type":"object"}},"required":["details"]}},{"if":{"properties":{"code":{"const":"quota_exceeded"}},"required":["code"]},"then":{"properties":{"details":{"properties":{"limit":{"pattern":"^[0-9]+(\\.[0-9]{1,3})?$","type":"string"},"period":{"enum":["hour","day","month"],"type":"string"},"remaining":{"pattern":"^[0-9]+(\\.[0-9]{1,3})?$","type":"string"},"reset_seconds":{"minimum":0,"type":"integer"},"scope":{"enum":["organization","key"],"type":"string"},"upgrade_url":{"type":"string"}},"required":["scope","upgrade_url"],"type":"object"}},"required":["details"]}}]}}},"description":"The key's or the organisation's burst is spent; retry after Retry-After seconds. The request would pass the period's credit quota; details say which quota and where to get more.","headers":{"Retry-After":{"description":"Seconds to wait before the next request would be served.","required":true,"schema":{"minimum":1,"type":"integer"}},"X-Correlation-ID":{"description":"The correlation ID of this request; quote it when reporting a problem.","required":true,"schema":{"pattern":"^cor_[0-9a-f]{32}$","type":"string"}},"X-Credits-Consumed":{"description":"The credits this request consumed, by the published formula.","required":false,"schema":{"minimum":0,"type":"number"}},"X-Quota-Limit":{"description":"The credits of the binding quota for the period.","required":false,"schema":{"minimum":0,"type":"number"}},"X-Quota-Period":{"description":"The quota period: hour, day or month.","required":false,"schema":{"enum":["hour","day","month"],"type":"string"}},"X-Quota-Remaining":{"description":"The credits of that quota left after this request.","required":false,"schema":{"minimum":0,"type":"number"}},"X-Quota-Reset":{"description":"Seconds until the quota period ends.","required":false,"schema":{"minimum":0,"type":"integer"}},"X-RateLimit-Limit":{"description":"The burst of the rate-limit bucket that binds this request.","required":false,"schema":{"minimum":0,"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in that bucket after this one.","required":false,"schema":{"minimum":0,"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until that bucket is full again.","required":false,"schema":{"minimum":0,"type":"integer"}},"X-Request-ID":{"description":"The ID this request's metering event is recorded under.","required":false,"schema":{"pattern":"^req_[0-9A-HJKMNP-TV-Z]{26}$","type":"string"}}}},"500":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"properties":{"code":{"enum":["internal_error"]}}}]}}},"description":"Something failed on our side; quote the correlation ID.","headers":{"X-Correlation-ID":{"description":"The correlation ID of this request; quote it when reporting a problem.","required":true,"schema":{"pattern":"^cor_[0-9a-f]{32}$","type":"string"}},"X-Credits-Consumed":{"description":"The credits this request consumed, by the published formula.","required":false,"schema":{"minimum":0,"type":"number"}},"X-RateLimit-Limit":{"description":"The burst of the rate-limit bucket that binds this request.","required":false,"schema":{"minimum":0,"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in that bucket after this one.","required":false,"schema":{"minimum":0,"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until that bucket is full again.","required":false,"schema":{"minimum":0,"type":"integer"}},"X-Request-ID":{"description":"The ID this request's metering event is recorded under.","required":false,"schema":{"pattern":"^req_[0-9A-HJKMNP-TV-Z]{26}$","type":"string"}}}},"503":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"properties":{"code":{"enum":["unavailable","rate_limit_unavailable","metering_unavailable"]}}}]}}},"description":"A dependency is out of reach or the dataset is being republished; try again shortly. Rate limiting cannot be consulted and this deployment refuses what it cannot limit. Usage cannot be recorded, and nothing is served unrecorded; try again shortly.","headers":{"Retry-After":{"description":"Seconds to wait before the next request would be served.","required":false,"schema":{"minimum":1,"type":"integer"}},"X-Correlation-ID":{"description":"The correlation ID of this request; quote it when reporting a problem.","required":true,"schema":{"pattern":"^cor_[0-9a-f]{32}$","type":"string"}},"X-Credits-Consumed":{"description":"The credits this request consumed, by the published formula.","required":false,"schema":{"minimum":0,"type":"number"}},"X-RateLimit-Limit":{"description":"The burst of the rate-limit bucket that binds this request.","required":false,"schema":{"minimum":0,"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in that bucket after this one.","required":false,"schema":{"minimum":0,"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until that bucket is full again.","required":false,"schema":{"minimum":0,"type":"integer"}},"X-Request-ID":{"description":"The ID this request's metering event is recorded under.","required":false,"schema":{"pattern":"^req_[0-9A-HJKMNP-TV-Z]{26}$","type":"string"}}}},"504":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"properties":{"code":{"enum":["query_timeout"]}}}]}}},"description":"The query ran longer than the service allows; narrow the filter or page with the cursor.","headers":{"X-Correlation-ID":{"description":"The correlation ID of this request; quote it when reporting a problem.","required":true,"schema":{"pattern":"^cor_[0-9a-f]{32}$","type":"string"}},"X-Credits-Consumed":{"description":"The credits this request consumed, by the published formula.","required":false,"schema":{"minimum":0,"type":"number"}},"X-RateLimit-Limit":{"description":"The burst of the rate-limit bucket that binds this request.","required":false,"schema":{"minimum":0,"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in that bucket after this one.","required":false,"schema":{"minimum":0,"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until that bucket is full again.","required":false,"schema":{"minimum":0,"type":"integer"}},"X-Request-ID":{"description":"The ID this request's metering event is recorded under.","required":false,"schema":{"pattern":"^req_[0-9A-HJKMNP-TV-Z]{26}$","type":"string"}}}}},"summary":"Query a published dataset with the specification in the request body.","tags":["Datasets"],"x-akiliq-key-operation":"query"}},"/v1/datasets/{dataset_id}/rows":{"get":{"description":"The Query Specification travels as JSON in the q parameter; a request with a matching If-None-Match is answered 304.","operationId":"readRows","parameters":[{"description":"The published dataset's ID.","in":"path","name":"dataset_id","required":true,"schema":{"pattern":"^ds_[0-9A-HJKMNP-TV-Z]{26}$","type":"string"}},{"description":"The ETag of a page already held.","in":"header","name":"If-None-Match","required":false,"schema":{"type":"string"}},{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuerySpecification"}}},"description":"The Query Specification as JSON; absent, the first page of every returnable field.","in":"query","name":"q","required":false}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Page"}}},"description":"A page of rows.","headers":{"ETag":{"description":"The page's strong entity tag; send it back in If-None-Match.","required":true,"schema":{"pattern":"^\"[^\"]+\"$","type":"string"}},"X-Correlation-ID":{"description":"The correlation ID of this request; quote it when reporting a problem.","required":true,"schema":{"pattern":"^cor_[0-9a-f]{32}$","type":"string"}},"X-Credits-Consumed":{"description":"The credits this request consumed, by the published formula.","required":true,"schema":{"minimum":0,"type":"number"}},"X-Quota-Limit":{"description":"The credits of the binding quota for the period.","required":false,"schema":{"minimum":0,"type":"number"}},"X-Quota-Period":{"description":"The quota period: hour, day or month.","required":false,"schema":{"enum":["hour","day","month"],"type":"string"}},"X-Quota-Remaining":{"description":"The credits of that quota left after this request.","required":false,"schema":{"minimum":0,"type":"number"}},"X-Quota-Reset":{"description":"Seconds until the quota period ends.","required":false,"schema":{"minimum":0,"type":"integer"}},"X-RateLimit-Limit":{"description":"The burst of the rate-limit bucket that binds this request.","required":false,"schema":{"minimum":0,"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in that bucket after this one.","required":false,"schema":{"minimum":0,"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until that bucket is full again.","required":false,"schema":{"minimum":0,"type":"integer"}},"X-Request-ID":{"description":"The ID this request's metering event is recorded under.","required":false,"schema":{"pattern":"^req_[0-9A-HJKMNP-TV-Z]{26}$","type":"string"}}}},"304":{"description":"The page is unchanged since the ETag sent; a tenth of the credits.","headers":{"ETag":{"description":"The page's strong entity tag; send it back in If-None-Match.","required":true,"schema":{"pattern":"^\"[^\"]+\"$","type":"string"}},"X-Correlation-ID":{"description":"The correlation ID of this request; quote it when reporting a problem.","required":true,"schema":{"pattern":"^cor_[0-9a-f]{32}$","type":"string"}},"X-Credits-Consumed":{"description":"The credits this request consumed, by the published formula.","required":true,"schema":{"minimum":0,"type":"number"}},"X-Quota-Limit":{"description":"The credits of the binding quota for the period.","required":false,"schema":{"minimum":0,"type":"number"}},"X-Quota-Period":{"description":"The quota period: hour, day or month.","required":false,"schema":{"enum":["hour","day","month"],"type":"string"}},"X-Quota-Remaining":{"description":"The credits of that quota left after this request.","required":false,"schema":{"minimum":0,"type":"number"}},"X-Quota-Reset":{"description":"Seconds until the quota period ends.","required":false,"schema":{"minimum":0,"type":"integer"}},"X-RateLimit-Limit":{"description":"The burst of the rate-limit bucket that binds this request.","required":false,"schema":{"minimum":0,"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in that bucket after this one.","required":false,"schema":{"minimum":0,"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until that bucket is full again.","required":false,"schema":{"minimum":0,"type":"integer"}},"X-Request-ID":{"description":"The ID this request's metering event is recorded under.","required":false,"schema":{"pattern":"^req_[0-9A-HJKMNP-TV-Z]{26}$","type":"string"}}}},"400":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"properties":{"code":{"enum":["query_invalid","query_malformed"]}}},{"if":{"properties":{"code":{"const":"query_invalid"}},"required":["code"]},"then":{"properties":{"details":{"properties":{"rejections":{"items":{"$ref":"#/components/schemas/Rejection"},"minItems":1,"type":"array"}},"required":["rejections"],"type":"object"}},"required":["details"]}}]}}},"description":"The dataset's descriptor refuses the query; details.rejections lists every reason. The Query Specification cannot be read: not a JSON object, another query parameter, or larger than 64 KiB.","headers":{"X-Correlation-ID":{"description":"The correlation ID of this request; quote it when reporting a problem.","required":true,"schema":{"pattern":"^cor_[0-9a-f]{32}$","type":"string"}},"X-Credits-Consumed":{"description":"The credits this request consumed, by the published formula.","required":false,"schema":{"minimum":0,"type":"number"}},"X-RateLimit-Limit":{"description":"The burst of the rate-limit bucket that binds this request.","required":false,"schema":{"minimum":0,"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in that bucket after this one.","required":false,"schema":{"minimum":0,"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until that bucket is full again.","required":false,"schema":{"minimum":0,"type":"integer"}},"X-Request-ID":{"description":"The ID this request's metering event is recorded under.","required":false,"schema":{"pattern":"^req_[0-9A-HJKMNP-TV-Z]{26}$","type":"string"}}}},"401":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"properties":{"code":{"enum":["unauthenticated"]}}}]}}},"description":"No API key, or one that is unknown, revoked, expired or of a deactivated organisation.","headers":{"WWW-Authenticate":{"description":"The authentication scheme the data API expects.","required":true,"schema":{"type":"string"}},"X-Correlation-ID":{"description":"The correlation ID of this request; quote it when reporting a problem.","required":true,"schema":{"pattern":"^cor_[0-9a-f]{32}$","type":"string"}}}},"403":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"properties":{"code":{"enum":["operation_not_permitted"]}}},{"if":{"properties":{"code":{"const":"operation_not_permitted"}},"required":["code"]},"then":{"properties":{"details":{"properties":{"operation":{"enum":["rows","query"],"type":"string"}},"type":"object"}},"required":["details"]}}]}}},"description":"The API key is not scoped to this operation.","headers":{"X-Correlation-ID":{"description":"The correlation ID of this request; quote it when reporting a problem.","required":true,"schema":{"pattern":"^cor_[0-9a-f]{32}$","type":"string"}},"X-Credits-Consumed":{"description":"The credits this request consumed, by the published formula.","required":false,"schema":{"minimum":0,"type":"number"}},"X-RateLimit-Limit":{"description":"The burst of the rate-limit bucket that binds this request.","required":false,"schema":{"minimum":0,"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in that bucket after this one.","required":false,"schema":{"minimum":0,"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until that bucket is full again.","required":false,"schema":{"minimum":0,"type":"integer"}},"X-Request-ID":{"description":"The ID this request's metering event is recorded under.","required":false,"schema":{"pattern":"^req_[0-9A-HJKMNP-TV-Z]{26}$","type":"string"}}}},"404":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"properties":{"code":{"enum":["not_found"]}}}]}}},"description":"No such dataset, not published, or outside the key's datasets: one answer for all three.","headers":{"X-Correlation-ID":{"description":"The correlation ID of this request; quote it when reporting a problem.","required":true,"schema":{"pattern":"^cor_[0-9a-f]{32}$","type":"string"}},"X-Credits-Consumed":{"description":"The credits this request consumed, by the published formula.","required":false,"schema":{"minimum":0,"type":"number"}},"X-RateLimit-Limit":{"description":"The burst of the rate-limit bucket that binds this request.","required":false,"schema":{"minimum":0,"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in that bucket after this one.","required":false,"schema":{"minimum":0,"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until that bucket is full again.","required":false,"schema":{"minimum":0,"type":"integer"}},"X-Request-ID":{"description":"The ID this request's metering event is recorded under.","required":false,"schema":{"pattern":"^req_[0-9A-HJKMNP-TV-Z]{26}$","type":"string"}}}},"413":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"properties":{"code":{"enum":["query_malformed"]}}}]}}},"description":"The Query Specification cannot be read: not a JSON object, another query parameter, or larger than 64 KiB.","headers":{"X-Correlation-ID":{"description":"The correlation ID of this request; quote it when reporting a problem.","required":true,"schema":{"pattern":"^cor_[0-9a-f]{32}$","type":"string"}},"X-Credits-Consumed":{"description":"The credits this request consumed, by the published formula.","required":false,"schema":{"minimum":0,"type":"number"}},"X-RateLimit-Limit":{"description":"The burst of the rate-limit bucket that binds this request.","required":false,"schema":{"minimum":0,"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in that bucket after this one.","required":false,"schema":{"minimum":0,"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until that bucket is full again.","required":false,"schema":{"minimum":0,"type":"integer"}},"X-Request-ID":{"description":"The ID this request's metering event is recorded under.","required":false,"schema":{"pattern":"^req_[0-9A-HJKMNP-TV-Z]{26}$","type":"string"}}}},"429":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"properties":{"code":{"enum":["rate_limited","quota_exceeded"]}}},{"if":{"properties":{"code":{"const":"rate_limited"}},"required":["code"]},"then":{"properties":{"details":{"properties":{"retry_after_seconds":{"minimum":1,"type":"integer"}},"required":["retry_after_seconds"],"type":"object"}},"required":["details"]}},{"if":{"properties":{"code":{"const":"quota_exceeded"}},"required":["code"]},"then":{"properties":{"details":{"properties":{"limit":{"pattern":"^[0-9]+(\\.[0-9]{1,3})?$","type":"string"},"period":{"enum":["hour","day","month"],"type":"string"},"remaining":{"pattern":"^[0-9]+(\\.[0-9]{1,3})?$","type":"string"},"reset_seconds":{"minimum":0,"type":"integer"},"scope":{"enum":["organization","key"],"type":"string"},"upgrade_url":{"type":"string"}},"required":["scope","upgrade_url"],"type":"object"}},"required":["details"]}}]}}},"description":"The key's or the organisation's burst is spent; retry after Retry-After seconds. The request would pass the period's credit quota; details say which quota and where to get more.","headers":{"Retry-After":{"description":"Seconds to wait before the next request would be served.","required":true,"schema":{"minimum":1,"type":"integer"}},"X-Correlation-ID":{"description":"The correlation ID of this request; quote it when reporting a problem.","required":true,"schema":{"pattern":"^cor_[0-9a-f]{32}$","type":"string"}},"X-Credits-Consumed":{"description":"The credits this request consumed, by the published formula.","required":false,"schema":{"minimum":0,"type":"number"}},"X-Quota-Limit":{"description":"The credits of the binding quota for the period.","required":false,"schema":{"minimum":0,"type":"number"}},"X-Quota-Period":{"description":"The quota period: hour, day or month.","required":false,"schema":{"enum":["hour","day","month"],"type":"string"}},"X-Quota-Remaining":{"description":"The credits of that quota left after this request.","required":false,"schema":{"minimum":0,"type":"number"}},"X-Quota-Reset":{"description":"Seconds until the quota period ends.","required":false,"schema":{"minimum":0,"type":"integer"}},"X-RateLimit-Limit":{"description":"The burst of the rate-limit bucket that binds this request.","required":false,"schema":{"minimum":0,"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in that bucket after this one.","required":false,"schema":{"minimum":0,"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until that bucket is full again.","required":false,"schema":{"minimum":0,"type":"integer"}},"X-Request-ID":{"description":"The ID this request's metering event is recorded under.","required":false,"schema":{"pattern":"^req_[0-9A-HJKMNP-TV-Z]{26}$","type":"string"}}}},"500":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"properties":{"code":{"enum":["internal_error"]}}}]}}},"description":"Something failed on our side; quote the correlation ID.","headers":{"X-Correlation-ID":{"description":"The correlation ID of this request; quote it when reporting a problem.","required":true,"schema":{"pattern":"^cor_[0-9a-f]{32}$","type":"string"}},"X-Credits-Consumed":{"description":"The credits this request consumed, by the published formula.","required":false,"schema":{"minimum":0,"type":"number"}},"X-RateLimit-Limit":{"description":"The burst of the rate-limit bucket that binds this request.","required":false,"schema":{"minimum":0,"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in that bucket after this one.","required":false,"schema":{"minimum":0,"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until that bucket is full again.","required":false,"schema":{"minimum":0,"type":"integer"}},"X-Request-ID":{"description":"The ID this request's metering event is recorded under.","required":false,"schema":{"pattern":"^req_[0-9A-HJKMNP-TV-Z]{26}$","type":"string"}}}},"503":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"properties":{"code":{"enum":["unavailable","rate_limit_unavailable","metering_unavailable"]}}}]}}},"description":"A dependency is out of reach or the dataset is being republished; try again shortly. Rate limiting cannot be consulted and this deployment refuses what it cannot limit. Usage cannot be recorded, and nothing is served unrecorded; try again shortly.","headers":{"Retry-After":{"description":"Seconds to wait before the next request would be served.","required":false,"schema":{"minimum":1,"type":"integer"}},"X-Correlation-ID":{"description":"The correlation ID of this request; quote it when reporting a problem.","required":true,"schema":{"pattern":"^cor_[0-9a-f]{32}$","type":"string"}},"X-Credits-Consumed":{"description":"The credits this request consumed, by the published formula.","required":false,"schema":{"minimum":0,"type":"number"}},"X-RateLimit-Limit":{"description":"The burst of the rate-limit bucket that binds this request.","required":false,"schema":{"minimum":0,"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in that bucket after this one.","required":false,"schema":{"minimum":0,"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until that bucket is full again.","required":false,"schema":{"minimum":0,"type":"integer"}},"X-Request-ID":{"description":"The ID this request's metering event is recorded under.","required":false,"schema":{"pattern":"^req_[0-9A-HJKMNP-TV-Z]{26}$","type":"string"}}}},"504":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/Error"},{"properties":{"code":{"enum":["query_timeout"]}}}]}}},"description":"The query ran longer than the service allows; narrow the filter or page with the cursor.","headers":{"X-Correlation-ID":{"description":"The correlation ID of this request; quote it when reporting a problem.","required":true,"schema":{"pattern":"^cor_[0-9a-f]{32}$","type":"string"}},"X-Credits-Consumed":{"description":"The credits this request consumed, by the published formula.","required":false,"schema":{"minimum":0,"type":"number"}},"X-RateLimit-Limit":{"description":"The burst of the rate-limit bucket that binds this request.","required":false,"schema":{"minimum":0,"type":"integer"}},"X-RateLimit-Remaining":{"description":"Requests left in that bucket after this one.","required":false,"schema":{"minimum":0,"type":"integer"}},"X-RateLimit-Reset":{"description":"Seconds until that bucket is full again.","required":false,"schema":{"minimum":0,"type":"integer"}},"X-Request-ID":{"description":"The ID this request's metering event is recorded under.","required":false,"schema":{"pattern":"^req_[0-9A-HJKMNP-TV-Z]{26}$","type":"string"}}}}},"summary":"Read a page of a published dataset's rows.","tags":["Datasets"],"x-akiliq-key-operation":"rows"}}},"security":[{"ApiKey":[]}],"servers":[{"description":"Your deployment's data API address.","url":"{base_url}","variables":{"base_url":{"default":"http://localhost:8080"}}}],"x-akiliq-changelog":[{"changes":[{"kind":"added","text":"Read a published dataset's rows with GET /v1/datasets/{dataset_id}/rows, or with the specification in the body of POST /v1/datasets/{dataset_id}/query."},{"kind":"added","text":"Filters, sorting, field selection, search, sealed cursors and ETags with If-None-Match."},{"kind":"added","text":"API keys, live and sandbox, scoped to datasets and operations, with per-key and per-organisation rate limits."},{"kind":"added","text":"Credits on every response, credit quotas per period, and the X-Quota and X-Credits-Consumed headers."},{"kind":"added","text":"The OpenAPI 3.1 document, the deprecation policy and this changelog."}],"date":"2026-09-26","version":"v1"}],"x-akiliq-deprecations":[],"x-akiliq-errors":[{"code":"query_invalid","statuses":[400],"description":"The dataset's descriptor refuses the query; details.rejections lists every reason."},{"code":"query_malformed","statuses":[400,413],"description":"The Query Specification cannot be read: not a JSON object, another query parameter, or larger than 64 KiB."},{"code":"unauthenticated","statuses":[401],"description":"No API key, or one that is unknown, revoked, expired or of a deactivated organisation."},{"code":"operation_not_permitted","statuses":[403],"description":"The API key is not scoped to this operation."},{"code":"not_found","statuses":[404],"description":"No such dataset, not published, or outside the key's datasets: one answer for all three."},{"code":"method_not_allowed","statuses":[405],"description":"The resource does not answer that method."},{"code":"precondition_failed","statuses":[412],"description":"A POST whose If-None-Match matched the current representation."},{"code":"rate_limited","statuses":[429],"description":"The key's or the organisation's burst is spent; retry after Retry-After seconds."},{"code":"quota_exceeded","statuses":[429],"description":"The request would pass the period's credit quota; details say which quota and where to get more."},{"code":"internal_error","statuses":[500],"description":"Something failed on our side; quote the correlation ID."},{"code":"unavailable","statuses":[503],"description":"A dependency is out of reach or the dataset is being republished; try again shortly."},{"code":"rate_limit_unavailable","statuses":[503],"description":"Rate limiting cannot be consulted and this deployment refuses what it cannot limit."},{"code":"metering_unavailable","statuses":[503],"description":"Usage cannot be recorded, and nothing is served unrecorded; try again shortly."},{"code":"query_timeout","statuses":[504],"description":"The query ran longer than the service allows; narrow the filter or page with the cursor."}]}