REST API overview

Base URL, authentication, response shapes, and errors.

Every API endpoint is scoped to your organization and follows the same URL pattern: https://www.inventra.sh/api/organizations/{orgId}/{resource}. This page covers the conventions shared across all endpoints. Individual resource pages cover the specifics.

Base URL

https://www.inventra.sh/api/organizations/{orgId}

orgId is your organization's ID, visible in the dashboard URL and in the Settings → API keys page.

Authentication

Every API-key-authenticated request must include the x-api-key header:

x-api-key: ivt_live_xxx

If the key is missing, invalid, or doesn't match the organization, the API returns 401 Unauthorized. See the Quickstart for how to generate a key.

Response shape

List endpoints return a flat array of published content:

{ "items": [ /* ... */ ] }

No pagination. Individual resource pages document the shape of each item.

Error shape

Validation errors return HTTP 400 with the full Zod issues array:

{
  "error": [
    {
      "code": "invalid_type",
      "expected": "string",
      "received": "number",
      "path": ["title"],
      "message": "Expected string, received number"
    }
  ]
}

Authentication and authorization failures return:

{ "error": "Unauthorized" }

Server errors return 500 with:

{ "error": "Internal Server Error" }

Content types

All request and response bodies are JSON. Content-Type: application/json is set on every response. POST bodies must also declare Content-Type: application/json.

Next steps

PreviousMCP serverNextBlocks