> ## Documentation Index
> Fetch the complete documentation index at: https://docs.graphora.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```text theme={null}
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.

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

## API Endpoints

The Graphora API is organized around the following main resources:

<CardGroup cols={2}>
  <Card title="Ontology" icon="sitemap">
    Create, retrieve, and manage ontologies
  </Card>

  <Card title="Transform" icon="file-lines">
    Upload and process documents
  </Card>

  <Card title="Merge" icon="code-merge">
    Merge extracted data into knowledge graphs
  </Card>

  <Card title="Graph" icon="diagram-project">
    Query and manipulate graph data
  </Card>

  <Card title="Dashboard" icon="chart-line">
    Retrieve KPIs, time-series performance, and recent runs for monitoring
  </Card>
</CardGroup>

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:

<Card title="Python Client Library" icon="python" href="/client/introduction">
  Use the Graphora client library in your Python applications
</Card>

## 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.