API Reference

The Graphomics knowledge graph is served by the MicroMap API — a REST API, version 1.0.0, under the base path /api/v1. Agent-callable capabilities across MapForge and Workbench are additionally exposed as MCP tools.

REST endpoints — the full knowledge-graph endpoint catalog.
MCP tools — every agent-callable tool.
Schemas — graph labels, relationships, and provenance contracts.

Base URL

All endpoints live under the /api/v1 base path. Your API base URL is issued by us when your organization is provisioned — there is no shared public endpoint. Examples in these docs use $GRAPHOMICS_API_URL (your REST base URL, ending in /api/v1) in place of the address you were given.

Your provisioned instance also serves an OpenAPI specification — the always-current source of truth for request parameters and response schemas.

Authentication

Authenticate every request with your API key in the X-API-Key header:

bash

curl -s $GRAPHOMICS_API_URL/stats \
  -H "X-API-Key: $GRAPHOMICS_API_KEY"

A bearer token is also accepted via the standard Authorization header:

bash

curl -s $GRAPHOMICS_API_URL/stats \
  -H "Authorization: Bearer $GRAPHOMICS_TOKEN"

Organization scoping. Your credential resolves to an organization_id, and all reads, writes, and assertions are scoped to your organization automatically. There are no per-endpoint scopes to manage — the organization boundary is the access boundary.

A missing or invalid key returns 401:

json

{ "detail": "Invalid or missing API key" }

Errors

Errors use a consistent JSON shape:

json

{ "detail": "Human-readable message" }

Request-validation errors (422) return a structured list:

json

{
  "detail": [
    { "loc": ["query", "limit"], "msg": "...", "type": "..." }
  ]
}

Status	Meaning
`200`	Success
`401`	Missing or invalid credential
`403`	Authenticated, but not permitted (e.g. cross-organization access)
`404`	Not found
`422`	Request validation failed
`429`	Rate limit exceeded
`503`	Backend (graph) unavailable

Pagination

List endpoints use offset-based pagination with limit and offset:

Parameter	Default	Min	Max
`limit`	`100`	`1`	`1000`
`offset`	`0`	`0`	—

Paginated responses include the totals:

json

{ "total": 1234, "limit": 100, "offset": 0, "results": [ ] }

Rate limits

The default policy is 100 requests per minute per API key. Requests over the limit receive 429 Too Many Requests.

Client libraries

There is no official SDK yet — the API is standard REST and works with any HTTP client (curl, httpx, requests, fetch). Agent developers should prefer the MCP tools, which handle the calls for you.