Skip to content
Sencai.docs

Platform API overview

Sencai’s platform is built on a REST API that the web app itself calls - this section documents the parts of it you can reach directly, for scripts, the official SDKs, and AI-agent integrations.

Base URL and versioning

Section titled “Base URL and versioning”
https://api.sencai.space/api/v1

Every path in this section is relative to that base. The API is versioned by this URL prefix; there is currently one version, v1. See API versioning for how the platform maintains version lifecycle information going forward.

Authentication

Section titled “Authentication”

There are two ways a request authenticates:

  • A personal access token (sencai_pat_...) - the practical option for scripts, the SDKs, and AI-agent integrations. A token authenticates as you and is scoped to your organization automatically; you never pass an organization ID yourself. See API tokens for how to create one, and note that a token currently reaches a specific, self-scoped set of endpoints (your organization’s own data, plus a handful of gated actions) rather than every resource in the API - the exact set is documented on that page and on AI agents (MCP).
  • Your signed-in session - what the web app itself uses while you’re logged in at app.sencai.space. This isn’t something you’d typically wire into your own script, since it depends on your interactive login (including any two-factor step) rather than a long-lived credential.

Every authenticated request is automatically scoped to your organization (or, for a personal access token, the single organization the token belongs to) - you never need to pass an organization identifier in a header or query parameter to establish who a request is acting on behalf of.

Request and response conventions

Section titled “Request and response conventions”
  • Request and response bodies are JSON.
  • A successful response wraps its result in a data field: {"data": {...}} for a single resource, {"data": [...]} for a list.
  • Paginated list endpoints additionally return a meta.pagination object with page, pageSize, total, and pageCount. Request a specific page with the page and pageSize query parameters (pageSize is capped, typically at 100).
  • Filtering is endpoint-specific - most list endpoints are automatically scoped to your own organization’s data rather than accepting a generic filter query language, so check the specific endpoint you’re calling (or the corresponding SDK method) for what it accepts.

Errors

Section titled “Errors”

Errors follow RFC 7807 Problem Details as application/problem+json:

{
  "type": "https://sencai.space/problems/not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "Organisation not found"
}

Common statuses you’ll encounter: 400 (validation), 401 (authentication required or invalid), 402 (your plan doesn’t include this), 403 (authenticated, but not allowed to do this), 404 (not found, or you don’t have access - the API deliberately doesn’t distinguish the two), 409 (conflict), 429 (too many requests), and 503 (a dependency the platform relies on is temporarily unavailable - retry later).

Rate limiting

Section titled “Rate limiting”

There’s no published, fixed per-request rate limit for direct API calls today. Personal-access-token access is already scoped to a narrow set of endpoints with its own gates (see API tokens); sustained high-volume or abusive traffic may still be throttled without prior notice.

A first request

Section titled “A first request”
Terminal window
curl https://api.sencai.space/api/v1/organisations/me \
  -H "Authorization: Bearer sencai_pat_..."
{
  "data": {
    "id": 42,
    "documentId": "a1b2c3d4e5f6...",
    "name": "Acme Cloud",
    "account_tier": "professional",
    "max_instances": 50,
    "max_members": 25,
    "max_monthly_budget": 5000,
    "createdAt": "2026-03-01T12:00:00.000Z"
  }
}

Resource families

Section titled “Resource families”

The API’s shape mirrors what you see in the app. A handful of families, by path prefix:

FamilyPath prefix
Organizations/organisations
Cloud instances/cloud-instances
Cloud networks & firewalls/cloud-networks, /cloud-security-groups
DNS zones/dns-zones
Fleet agents/sencai-agents
Runbooks & executions/runbooks, /runbook-executions
Incidents/incidents
Cost records/cost-records
Compliance controls/compliance-controls
Audit log/audit-logs
Customer webhooks/customer-webhooks
API tokens/api-keys

Most of these require the same signed-in session the web app itself uses. A personal access token only reaches the narrower, self-scoped surface covered in API tokens and AI agents (MCP) - treat this table as an orientation map, not a guarantee that every path on it is reachable with a token.

What’s next

Section titled “What’s next”