mantle← Documentation

Developers

REST API reference

The HTTP surface mantle exposes at https://api.mantleai.dev/v1— authenticate with the same Bearer API key you'd use for MCP.

OpenAPI

Generate a typed client from our spec: api.mantleai.dev/openapi.json. Works with openapi-typescript, openapi-python-client, Postman, Scalar.

Most users will never touch the REST API directly — their agent uses MCP instead. Reach for this surface when:

  • You're writing a server-side integration and don't want to run an MCP client
  • You need batch operations that don't fit the MCP conversational shape
  • You're wiring mantle into a custom dashboard or admin tool
  • You want to debug what an agent is actually calling (MCP tools forward to these endpoints under the hood)

Authentication

Every endpoint requires Authorization: Bearer <key>. API keys look like mk_... and are issued from the dashboard at app.mantleai.dev.

curl https://api.mantleai.dev/v1/sources \
  -H "Authorization: Bearer mk_your_key_here"

Scopes ride on the key. A read-scoped key can call every read endpoint; write is required for sync triggers and mutations; admin is required for things like bulk-revoke on the api-keys endpoints. Scopes are hierarchical — admin grants write grants read.

Rate limits: 300 requests/minute per API key by default. Specific endpoints are tighter (create-key is 10/min, sync-trigger is 20/min). Rate-limit hits return 429 Too Many Requests. See specific endpoint docs for per-route limits.

OpenAPI

The full, always-current schema lives at https://api.mantleai.dev/openapi.json. Every endpoint, parameter, response shape, and status code is documented there. If you use a tool that ingests OpenAPI (Postman, Insomnia, Scalar, openapi-typescript, openapi-python-client), point it at that URL and you'll have a working client in seconds.

This page gives you a curated tour; the OpenAPI spec is the authoritative reference.

Endpoint groups

Search & graph

POST/v1/search
POST/v1/search/relationships
GET/v1/search/entities
GET/v1/search/entities/{id}
GET/v1/search/entities/{id}/context
GET/v1/search/entities/{id}/relationships
GET/v1/search/entities/{id}/relationships/summary
POST/v1/search/entities/degrees
GET/v1/search/entities/{id}/path?to={id}
GET/v1/search/entities/{id}/graph

Sources

GET/v1/sources
POST/v1/sources
GET/v1/sources/{id}
DELETE/v1/sources/{id}
PATCH/v1/sources/{id}
POST/v1/sources/{id}/sync
GET/v1/sources/{id}/events
GET/v1/sources/{id}/files
POST/v1/sources/{id}/files/purge
GET/v1/sources/{id}/failures
POST/v1/sources/{id}/retry-failures
POST/v1/sources/{id}/query

API keys

POST/v1/api-keys
GET/v1/api-keys
PATCH/v1/api-keys/{id}
DELETE/v1/api-keys/{id}
POST/v1/api-keys/{id}/rotate
POST/v1/api-keys/revoke-all

Documents & content

GET/v1/sources/{source_id}/content/{file_id}
GET/v1/sources/{source_id}/files/{file_id}/chunks
GET/v1/chunks/{chunk_id}/context

Auth

GET/v1/auth/login-url
POST/v1/auth/callback
POST/v1/auth/refresh
GET/v1/auth/me

Connectors & sync

GET/v1/connectors
POST/v1/sources/{id}/oauth/start
POST/v1/sources/{id}/oauth/callback
POST/v1/sources/{id}/cleanup-preview

Usage

GET/v1/usage/balance
GET/v1/usage/events

Tenants

DELETE/v1/tenants/{tenant_id}

Health & status

GET/v1/health
GET/v1/ready
GET/v1/stats
GET/v1/status/public

Example — full roundtrip

Search for an entity, pull its context, and read the top linked document:

# 1. Resolve the name
curl -s https://api.mantleai.dev/v1/search/entities?q=brickell \
  -H "Authorization: Bearer mk_..." | jq '.[0].entity_id'
# → "ent_0e19a8f4..."

# 2. Pull the snapshot
curl -s "https://api.mantleai.dev/v1/search/entities/ent_0e19a8f4.../context" \
  -H "Authorization: Bearer mk_..." | jq '.entity.name, .entity.properties, .relationships[:3]'

# 3. Fetch full document content for a related file
curl -s "https://api.mantleai.dev/v1/sources/src_xyz/content/file_abc" \
  -H "Authorization: Bearer mk_..." | jq '.content[:500]'

Errors

Errors return standard HTTP status codes plus a JSON body:

{
  "detail": "Authorization required. Provide a Bearer token in the Authorization header."
}

Common codes:

  • 401 Unauthorized — missing or invalid Bearer token
  • 402 Payment Required — tenant is out of credits; contact hello@mantleai.dev to top up
  • 403 Forbidden — your API key doesn't have the required scope
  • 404 Not Found — entity/source/file not found, or not visible to your tenant
  • 429 Too Many Requests — rate limit exceeded; respect Retry-After header
  • 5xx — something's broken on our side; retry with exponential backoff. If persistent, ping hello@mantleai.dev with the X-Request-Id header from the response.

Changelog

Breaking changes to public endpoints are rare but announced in advance via the changelog. Endpoints prefixed /v1/ are stable; anything under /v0/ (none today) would be considered unstable.