Open API v1

Conventions

Versioning

Public endpoints live under /open/v1. Breaking changes ship as /open/v2. Additive fields and new endpoints are not breaking.

/v2/contact and /v2/ticket are the previous partner surface. They stay available while deprecated. Prefer /open/v1.

Pagination

List endpoints return a cursor page, newest first:

json

{
  "object": "list",
  "data": [{ "id": "..." }],
  "has_more": true,
  "next_cursor": "65f1c2a4b9d3e40012ab34cd"
}

Query parameters:

Name	Default	Notes
`limit`	`25`	Max `100`
`starting_after`	—	Pass the previous `next_cursor`

Errors

Every error uses the same envelope:

json

{
  "error": {
    "type": "invalid_request_error",
    "code": "validation_error",
    "message": "One or more parameters are invalid.",
    "details": [{ "param": "name", "message": "Required" }],
    "request_id": "0c1e..."
  }
}

Branch on code, not on message.

Code	HTTP	Meaning
`invalid_api_key`	401	Missing, unknown, revoked, or expired key
`insufficient_scope`	403	Key is missing the required scope
`not_found`	404	Resource does not exist or belongs to another workspace
`validation_error`	422	Request parameters failed validation
`conflict`	409	Idempotency key is still in flight
`rate_limit_exceeded`	429	Too many requests for this key
`internal_error`	500	Unexpected server error

Quote request_id (also sent as X-Request-Id) when you contact support.

Cross-tenant ids return 404, not 403, so one workspace cannot probe another.

Rate limits

Limits are per API key, per minute.

Tier	Requests / minute
`free`	60
`standard`	300
`partner`	1200

Response headers:

http

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 299
X-RateLimit-Reset: 1710000060
Retry-After: 12

429 includes Retry-After in seconds.

Idempotency

POST can send Idempotency-Key (any string unique to that create). A replay within 24 hours returns the original success response with Idempotent-Replay: true. A key still in flight returns 409. Failed attempts are not replayed.

Request ids

Send your own X-Request-Id or accept the one TaggoAI generates. It is echoed on every response.

CORS

/open/v1 is a server-to-server API. Keys must not be used from browsers.