Overview

Base URL#

https://systematlas.org/api/v1

Requests#

• Authenticate with Authorization: Bearer sa_…. Public endpoints work without it. See Authentication.
• Send bodies as JSON with content-type: application/json. Unknown fields are ignored.
• Slugs in paths are the workspace slug and the company slug; the client company is always client.

Responses#

Success wraps the result in data; failure wraps a code and message in error, with the matching HTTP status.

{
  "data": [
    {
      "slug": "acme-builders",
      "name": "Acme Builders",
      "status": "active",
      "companies": 5
    }
  ]
}

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "A valid API key is required."
  }
}

Endpoints#

Every REST endpoint has an MCP tool that does the same thing. The full reference, with parameters and examples, is generated from the router.

• GET/api/v1/industriesList industries
• GET/api/v1/industries/:keyGet an industry schema
• GET/api/v1/searchSearch the registry
• GET/api/v1/glossaryGet the glossary
• GET/api/v1/workspacesList workspaces
• GET/api/v1/workspaces/:slugGet a workspace
• GET/api/v1/workspaces/:slug/companies/:companyGet a company atlas
• GET/api/v1/workspaces/:slug/compareCompare companies
• GET/api/v1/workspaces/:slug/research/:runGet a research run
• GET/api/v1/workspaces/:slug/mapping-guideGet the mapping guide
• POST/api/v1/workspacesCreate your workspace
• POST/api/v1/workspaces/:slug/companiesAdd a competitor
• POST/api/v1/workspaces/:slug/companies/:company/researchStart research
• POST/api/v1/workspaces/:slug/upload/componentsUpload components
• POST/api/v1/workspaces/:slug/upload/flowsUpload flows
• POST/api/v1/workspaces/:slug/upload/notesUpload notes
• POST/api/v1/workspaces/:slug/upload/screenshotUpload a screenshot
• GET/api/v1/workspaces/:slug/screenshotsList screenshots
• GET/api/v1/workspaces/:slug/draftsList drafts
• POST/api/v1/workspaces/:slug/drafts/reviewReview drafts
• POST/api/v1/contributionsContribute facts
• POST/api/v1/proposalsPropose a primitive
• POST/api/v1/workspaces/:slug/optimal-engine/sendSend to Optimal Engine
• POST/api/v1/workspaces/:slug/optimal-engine/pullPull from Optimal Engine
• GET/api/v1/workspaces/:slug/optimal-engine/exportExport for a local Optimal Engine
• POST/api/v1/workspaces/:slug/optimal-engine/importImport from a local Optimal Engine
• GET/api/v1/admin/registry/guideRegistry authoring guide
• POST/api/v1/admin/registry/organizationsUpsert a registry organization
• POST/api/v1/admin/registry/componentsUpsert registry components
• POST/api/v1/admin/registry/flowsUpsert registry flows
• POST/api/v1/admin/registry/notesUpsert registry notes
• POST/api/v1/admin/registry/gapsUpsert registry gaps
• POST/api/v1/admin/registry/taxonomyUpsert taxonomy nodes
• POST/api/v1/admin/registry/schemasUpsert an industry schema

Upload from a checkout#

To post JSON or NDJSON files in batches from a checkout of the System Atlas repo, use the upload script. It calls the upload endpoints for you.

SYSTEMATLAS_URL=https://systematlas.org SYSTEMATLAS_API_KEY=sa_… \
  pnpm atlas:upload ./atlas --workspace <slug>