REST API

Everything the app and the MCP server do goes through one JSON API. The reference in this section is generated from the same endpoint definitions that validate each request, so it can’t drift from what the API accepts.

Base URL

https://api.adventur.ai

Every path starts with /v1. Workspace data lives under /v1/orgs/{orgId}/…, where orgId is the workspace’s id.

Authentication

Send the token as a bearer header:

curl https://api.adventur.ai/v1/orgs/$ORG_ID/marketing/posts \
  -H "Authorization: Bearer $TOKEN"

Tokens are scoped to one user and one workspace, and carry that member’s role and permissions. A request for another workspace, or one the role can’t perform, gets 403.

Requests and responses

Bodies are JSON (Content-Type: application/json), apart from file uploads, which go straight to storage through a signed URL.

Successful responses wrap their payload in data:

{ "data": { "id": "3f8e2c1a-…", "status": "pending_approval" } }

Timestamps are ISO 8601 in UTC, and ids are UUIDs.

Lists, filters and pages

List endpoints take page and limit, and return the page with its totals:

{
  "data": {
    "items": [],
    "page": 1,
    "limit": 20,
    "total": 42,
    "hasMore": true
  }
}

Where an endpoint supports filters and sorting, they use filter[field], filterOp[field] and sortBy / sortDir:

curl "https://api.adventur.ai/v1/orgs/$ORG_ID/marketing/posts?filter[status]=scheduled&filterOp[status]=eq&sortBy=scheduledForUtc&sortDir=asc" \
  -H "Authorization: Bearer $TOKEN"

Errors

Errors come back as JSON with a human-readable error and, where a client should branch on it, a stable code:

{
  "error": "An active paid plan is required to access this resource",
  "code": "subscription_required"
}

Status	When	`code` you may see
`400`	The body, query or path didn’t validate.	none; `details` lists each problem
`401`	The token is missing, invalid or expired.	none
`402`	The plan doesn’t allow it right now.	`subscription_required`, `subscription_overdue_read_only`, `fair_use_limit`
`403`	The member’s role doesn’t allow it.	none
`404`	The resource doesn’t exist in this workspace.	none
`429`	Too many requests.	`rate_limit_exceeded`, with `retryAfterSeconds`

A workspace whose payment is overdue goes read-only: reads keep working and writes get 402 subscription_overdue_read_only until the invoice is paid.

Reference and spec

Endpoint referenceEvery public endpoint, grouped by area, with parameters, bodies, responses and the MCP tool that calls it.

OpenAPI 3 specImport into Postman, Insomnia or a code generator. Also served live at /v1/openapi.json.