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

# API overview

> Build on Ardent with the REST API

The Ardent API lets you create projects, connect Postgres sources, create branches, poll long-running operations, and manage organization access from your own automation.

Use the CLI for interactive setup and day-to-day terminal work. Use the API when you are building CI systems, internal developer platforms, custom dashboards, or agent workflows.

## Base URL

```text theme={null}
https://api.tryardent.com/v1
```

All examples use JSON over HTTPS and assume your token is stored in `ARDENT_TOKEN`.

## Authentication

Pass an API token with each request:

```bash theme={null}
curl -H "Authorization: Bearer $ARDENT_TOKEN" https://api.tryardent.com/v1/projects
```

Create and revoke tokens in **Ardent dashboard > Settings > API keys**, or via the [API keys endpoints](/api/api-keys). See [Authentication](/api/authentication) for token handling, roles, and troubleshooting.

## Resource model

```text theme={null}
Organization
  └─ Project
       └─ Connector
            └─ Branch
```

* **Organization**: your team and billing/security boundary.
* **Project**: a workspace for related connectors and branches.
* **Connector**: one Postgres source server that Ardent can replicate and branch.
* **Branch**: an isolated database created from a connector.

## A minimal API flow

1. List or create a project.
2. Preflight a Postgres source.
3. Create a connector after preflight passes.
4. Create a branch from the connector — this returns an operation ID.
5. Poll the operation; when it completes, `result.branch_url` is the connection string for your app, test runner, or agent.

```bash theme={null}
curl -H "Authorization: Bearer $ARDENT_TOKEN"   -X POST https://api.tryardent.com/v1/branch/create   -H 'Content-Type: application/json'   -d '{"connector_id":"conn_123","service_type":"postgres","name":"pr-123"}'
```

For Postgres branches, `service_type` is `postgres` — not the connector type `postgresql`. The create call returns `202 Accepted` with an `operation_id` — see [Branches](/api/branches) for the full flow.

## Long-running work

Some API calls return immediately with an operation ID while Ardent continues the work in the background. Connector discovery and setup are the most common examples.

```bash theme={null}
curl -H "Authorization: Bearer $ARDENT_TOKEN" https://api.tryardent.com/v1/operations/op_123
```

See [Operations](/api/operations) for the full polling model.

## Stability notes

Read the fields you need and ignore unknown ones — the API may add fields over time. Treat missing required fields, failed operations, and empty branch URLs as hard failures in automation. See [Errors](/api/errors) for status codes and retry guidance.