Graphora API Reference

Reference documentation for the Graphora API

Graphora API Reference

The Graphora API provides programmatic access to the Graphora platform, allowing you to manage ontologies, transform documents, and work with knowledge graphs. This reference documents the endpoints available in the Graphora API.

Base URLs

https://api.graphora.io/api/v1          # production / staging
http://localhost:8000/api/v1            # docker compose stack (make dev-up)

Set GRAPHORA_API_URL (or PUBLIC_API_URL in the API .env) to point your clients at the desired environment.

Health endpoints

• GET /health – lightweight liveness probe used by load balancers.
• GET /ready – readiness probe that verifies Redis and Prefect connectivity. The docker compose file uses it to determine when the stack is usable.

Authentication

Graphora relies on Clerk for authentication and session management. Every request must include a valid Clerk JWT in the Authorization header:

Authorization: Bearer YOUR_CLERK_JWT

Obtain tokens by integrating Clerk in your frontend or by using Clerk’s server-side APIs. For pipelines, create a Clerk JWT template (e.g., graphora_pipeline), mint a short-lived token via POST /v1/users/<id>/tokens/<template>, and pass it as GRAPHORA_AUTH_TOKEN before invoking the API. Tokens expire, so ensure your client refreshes sessions when required.

Never expose long-lived service keys or raw JWTs in public repositories or client-side code. Rotate credentials immediately if compromise is suspected.

API Endpoints

The Graphora API is organized around the following main resources:

Ontology

Create, retrieve, and manage ontologies

Transform

Upload and process documents

Merge

Merge extracted data into knowledge graphs

Graph

Query and manipulate graph data

Dashboard

Retrieve KPIs, time-series performance, and recent runs for monitoring

The dashboard suite exposes GET /api/v1/dashboard/summary, /performance, /quality, and /runs (also available as /transform/runs for backward compatibility).

Extraction modes

The Transform API offers three extraction modes — pick based on how much schema work you want to do up front:

Endpoint	When to use	ontology_id required?
POST /api/v1/transform/{ontology_id}/upload	You already have a registered ontology you want to enforce	Yes — register via POST /api/v1/ontology first
POST /api/v1/transform/upload	Zero-config — let the API infer an ontology from document text before extracting	No
POST /api/v1/transform/schemaless/upload	You want extraction with a generic schema, then refine the ontology after seeing what was extracted (no pre-extraction bias)	No — refine post-hoc via GET /transform/{id}/inferred-ontology + POST /transform/{id}/finalize-ontology

If you’re prototyping or onboarding a new corpus, start with /transform/upload — it’s the path with the lowest setup cost. The other two are tools for specific situations (enforce a known ontology, or defer schema decisions until you have evidence).

Client Libraries

While you can use the API directly with HTTP requests, we recommend using our client libraries for a more convenient experience:

Python Client Library

Use the Graphora client library in your Python applications

Rate Limits

The Graphora API has rate limits to ensure fair usage and system stability. The current limits are:

• 100 requests per minute per authenticated user/session
• 5,000 requests per day per authenticated user/session

If you exceed these limits, you’ll receive a 429 Too Many Requests response.