### POST /v1/connectors/{connector_id}/engine-setup

Source: https://docs.tryardent.com/api/connectors/engine-setup

Starts an asynchronous engine setup for the specified connector. If setup is already running, the request joins the existing operation. If the engine is already set up, it returns the connector details immediately.

```APIDOC
## POST /v1/connectors/{connector_id}/engine-setup

### Description
Starts async setup and returns an operation handle. If setup is already running, the call joins it. If the engine is already set up, the call returns 200 with the connector details.

### Method
POST

### Endpoint
/v1/connectors/{connector_id}/engine-setup

### Parameters
#### Path Parameters
- **connector_id** (string) - Required - The unique identifier of the connector.

### Response
#### Success Response (200)
- **ConnectorRow** (object) - Returned when the engine is already set up. Contains connector details including id, org_id, name, and service_name.

#### Success Response (202)
- **OperationHandle** (object) - Returned when setup is started or joined. Contains operation_id to poll for progress.

#### Error Responses
- **400** - The connector isn't in a state that can run setup.
- **403** - No update permission on this connector.
- **404** - Connector not found or not visible.
- **409** - A conflicting setup operation exists.
- **422** - Setup prerequisites failed.
- **503** - Ardent could not start the work.
```

--------------------------------

### POST /v1/connectors

Source: https://docs.tryardent.com/api/connectors

Stores connector configuration and starts the setup process.

```APIDOC
## POST /v1/connectors

### Description
Stores connector configuration and starts setup.

### Method
POST

### Endpoint
/v1/connectors
```

--------------------------------

### Manual Ardent CLI Setup

Source: https://docs.tryardent.com/

Follow these steps to manually install the CLI, authenticate, and configure your database connector.

```bash
Set up Ardent for database branching. Act like a teammate at my keyboard:
run the commands yourself, stop only when you need me to do something
only I can do (browser sign-up, paste a credential, run source-database SQL).
Before each step, give me one short line on what's happening and why.

Run these in order:

1. Install the CLI: npm install -g ardent-cli

2. ardent login → opens a browser to authenticate. Tell me to finish
   sign-up or login and ping you when done.

3. Tell me to export my Postgres connection string in this shell:
   export ARDENT_DB_URL='postgres://...'
   Then run:
   ardent connector preflight postgresql "$ARDENT_DB_URL"
   If preflight prints a Grant script, stop and ask me to run it on the
   source database, then re-run preflight until it passes.

4. After preflight passes, run:
   ardent connector create postgresql "$ARDENT_DB_URL"
   Setup runs server-side and may take minutes or longer depending on
   database size. If it's interrupted, resume with:
   ardent connector retry-setup <name>

5. ardent branch create my-feature → an isolated copy of my database
   I can use however I want without touching prod.

6. ardent branch info → hand me the connection URL. I connect to it
   like any Postgres database.

If a command errors, fix it. Docs: https://docs.tryardent.com/quickstart
```

--------------------------------

### Verify CLI Installation

Source: https://docs.tryardent.com/cli/overview

Check that the CLI is installed correctly.

```bash
ardent --version
```

--------------------------------

### Test wal2json plugin installation

Source: https://docs.tryardent.com/connectors/self-hosted

Verifies the wal2json plugin is correctly installed by creating and dropping a temporary replication slot.

```sql
SELECT pg_create_logical_replication_slot('ardent_probe', 'wal2json');
SELECT pg_drop_replication_slot('ardent_probe');
```

```sql
SELECT slot_name
FROM pg_replication_slots
WHERE slot_name = 'ardent_probe';
```

--------------------------------

### Example output: status

Source: https://docs.tryardent.com/cli/auth

Shows the output of the status command when authenticated.

```text
✓ Authenticated
  Account: Username
  Email:   username@tryardent.com
  Org:     Ardent
```

--------------------------------

### Retry connector setup

Source: https://docs.tryardent.com/cli/connectors

Attempts to finish or repair a connector setup while preserving existing credentials and configuration.

```bash
ardent connector retry-setup prod-db
```

```bash
ardent connector retry-setup prod-db --replica-identity-decisions ./decisions.json
ardent connector retry-setup prod-db --accept-replica-identity-defaults
```

--------------------------------

### Branch creation output

Source: https://docs.tryardent.com/cli/branches

Example output showing the successful creation of a branch and its connection URL.

```text
✓ Branch 'my-feature' created and checked out in 4.2s

postgresql://user:***@my-feature-postgres.routing.tryardent.com:5432/db?sslmode=require&channel_binding=disable
```

--------------------------------

### View Login Success Output

Source: https://docs.tryardent.com/quickstart

Example output displayed after a successful login.

```text
✓ Logged in as you@company.com

No projects found.
Create one with: ardent project create <name>
```

--------------------------------

### Example output: one project and one connector

Source: https://docs.tryardent.com/cli/auth

Shows the terminal output when a single project and connector are auto-selected after login.

```text
✓ Logged in as username@tryardent.com

  Auto-selected project 'my-app'
  Auto-selected connector 'my-app-db'
  Ready to branch:
  ardent branch create <name>
```

--------------------------------

### Example output: multiple projects

Source: https://docs.tryardent.com/cli/auth

Shows the terminal output when multiple projects are detected, requiring manual selection.

```text
✓ Logged in as username@tryardent.com

3 projects found.
Next step: select a project: ardent project switch <name>
List your projects: ardent project list
```

--------------------------------

### Preflight output example

Source: https://docs.tryardent.com/cli/connectors

Sample output showing the results of a preflight check, including connection status and required grant scripts.

```text
Running preflight against db.example.com:5432…

Connection checks:
  ✓ tcp reachable
  ✓ auth
  ✓ postgres metadata
  ✓ is writer
  ✓ wal level (actual: logical)
  ✓ replication slots (2/10 used)
  ✓ wal senders (max: 10)
  ✓ wal2json
  ✗ can read tables
      Missing SELECT on public.orders
      → Run the grant script below, then re-run preflight.

Detected source provider: vanilla

--- Grant script ---
-- psql artifact generated by Ardent
-- ...

✗ Preflight checks did NOT pass. Fix the failures above before creating.
```

--------------------------------

### Set up Ardent via AI Agent

Source: https://docs.tryardent.com/

Use this prompt with Claude Code or Cursor to automate the Ardent setup process.

```text
Set up Ardent for database branching on this project.
My connection string: [paste here]
```

--------------------------------

### Install Ardent CLI Skill

Source: https://docs.tryardent.com/workflows/ai-agents

Bash script to install the Ardent CLI skill into the project's .claude directory for automated agent usage.

```bash
mkdir -p .claude/skills/ardent-cli
tmp_skill="$(mktemp)"
if curl -fsS https://docs.tryardent.com/skills/ardent-cli-skill.txt -o "$tmp_skill"; then
  mv "$tmp_skill" .claude/skills/ardent-cli/SKILL.md
else
  rm -f "$tmp_skill"
  exit 1
fi
```

--------------------------------

### Install Ardent CLI

Source: https://docs.tryardent.com/cli/overview

Requires Node.js 18 or newer.

```bash
npm install -g ardent-cli
```

--------------------------------

### Check connector status

Source: https://docs.tryardent.com/cli/connectors

Retrieves health and setup progress for a specific connector.

```bash
ardent connector status prod-db
```

```text
Connector: prod-db
Service:   postgresql
Status:    Ready
```

--------------------------------

### Example JSON branch response

Source: https://docs.tryardent.com/cli/configuration

The structure returned by successful branch creation commands.

```json
{
  "schema_version": 3,
  "id": "br_123",
  "name": "pr-123",
  "connector_id": "conn_123",
  "service_type": "postgres",
  "status": "active",
  "branch_url": "postgresql://user:***@pr-123-postgres.routing.tryardent.com:5432/db?sslmode=require&channel_binding=disable",
  "pooled_branch_url": "postgresql://user:***@pr-123-pooler.routing.tryardent.com:5432/db?sslmode=require&channel_binding=disable",
  "pooled_branch_prisma_url": "postgresql://user:***@pr-123-pooler.routing.tryardent.com:5432/db?sslmode=require&channel_binding=disable",
  "created_at": "2026-06-01T12:00:00Z",
  "read_ready_at": "2026-06-01T12:00:05Z",
  "write_ready_at": "2026-06-01T12:00:05Z",
  "masked_ready_at": null,
  "last_branch_activity": null,
  "current": true,
  "warning": null
}
```

--------------------------------

### POST /v1/connectors/{connector_id}/discover

Source: https://docs.tryardent.com/api/connectors/discover

Starts async discovery of the source's schemas and tables. If discovery is already running, the call joins the existing operation.

```APIDOC
## POST /v1/connectors/{connector_id}/discover

### Description
Starts async discovery of the source's schemas and tables. Returns an operation handle that can be polled. If discovery is already running, the call joins it instead of starting another.

### Method
POST

### Endpoint
/v1/connectors/{connector_id}/discover

### Parameters
#### Path Parameters
- **connector_id** (string) - Required - The unique identifier of the connector.

### Response
#### Success Response (202)
- **operation_id** (string) - Operation to poll at GET /v1/operations/{operation_id}.
- **status** (string) - Status at acceptance time.
- **type** (string) - The kind of work this operation tracks.
- **resource_id** (string|null) - ID of the resource being created or acted on.
- **prerequisites** (object|null) - Pre-discovery prerequisite check results.
- **source_metadata** (object|null) - Metadata gathered from the source.

#### Response Example
{
  "operation_id": "op_12345",
  "status": "running",
  "type": "connector_discovery",
  "resource_id": "conn_abc",
  "prerequisites": null,
  "source_metadata": null
}
```

--------------------------------

### AI Agent Prompt for Postgres Setup

Source: https://docs.tryardent.com/connectors/self-hosted

Prompts for AI agents like Claude Code or Cursor to automate the verification process.

```text
Check whether my self-hosted Postgres database is ready to connect to Ardent.
My connection string: [paste here]
```

```text
Check whether my self-hosted Postgres database is ready to connect to Ardent.
My connection string: [paste here]

Use Ardent preflight first:
ardent connector preflight postgresql '<connection-string>' --schemas public

Then verify these source requirements and tell me exactly what to fix:
1. The host is reachable from Ardent over TLS on the Postgres port.
2. pg_hba.conf allows both normal and replication connections from Ardent's outbound IP.
3. wal_level is logical, max_wal_senders >= 10, max_replication_slots >= 10 (or higher if already higher, since these are minimums Ardent expects), and at least one replication slot is free.
4. wal2json is available. If you create a temporary slot to test it, immediately drop it; if the drop fails, stop and run SELECT pg_drop_replication_slot('ardent_probe'); before doing anything else.
5. The connection is to a writable primary, not a read replica: SELECT pg_is_in_recovery(); must return false.
6. The Ardent role has the grants from the preflight Grant script.
7. Tables selected for replication have a primary key, valid unique NOT NULL index, or REPLICA IDENTITY FULL.

After preflight passes, run:
ardent connector create postgresql '<connection-string>'
```

--------------------------------

### Engine Setup OpenAPI Definition

Source: https://docs.tryardent.com/api/connectors/engine-setup

OpenAPI specification for the POST /v1/connectors/{connector_id}/engine-setup endpoint, including request parameters and response schemas.

```yaml
openapi: 3.1.0
info:
  description: >-
    Public Ardent API. Generated by scripts/export_public_openapi.py — do not
    edit by hand.
  title: Ardent API
  version: v1
servers:
  - url: https://api.tryardent.com
security: []
paths:
  /v1/connectors/{connector_id}/engine-setup:
    post:
      tags:
        - v1-connectors
      summary: Engine Setup Endpoint
      operationId: engine_setup_endpoint_v1_connectors__connector_id__engine_setup_post
      parameters:
        - in: path
          name: connector_id
          required: true
          schema:
            title: Connector Id
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectorRow'
          description: >-
            Nothing to do: the engine is already set up. Returns the connector
            row with a `message`.
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OperationHandle'
          description: Setup started (or joined). Poll `GET /v1/operations/{operation_id}`.
        '400':
          description: The connector isn't in a state that can run setup.
        '403':
          description: No update permission on this connector.
        '404':
          description: Connector not found (or not visible to the caller).
        '409':
          description: A conflicting setup operation exists.
        '422':
          description: >-
            Setup prerequisites failed (for example, unresolved replica identity
            decisions).
        '503':
          description: Ardent could not start the work — safe to retry.
      security:
        - bearerAuth: []
components:
  schemas:
    ConnectorRow:
      additionalProperties: true
      properties:
        can_delete:
          anyOf:
            - type: boolean
            - type: 'null'
          description: Whether the caller may delete this connector.
          title: Can Delete
        can_update:
          anyOf:
            - type: boolean
            - type: 'null'
          description: Whether the caller may update this connector.
          title: Can Update
        created_at:
          anyOf:
            - type: string
            - type: 'null'
          description: When the connector was created.
          title: Created At
        id:
          description: Connector ID.
          title: Id
          type: string
        name:
          description: Connector name.
          title: Name
          type: string
        org_id:
          description: Organization the connector belongs to.
          title: Org Id
          type: string
        project_id:
          anyOf:
            - type: string
            - type: 'null'
          description: Project the connector belongs to.
          title: Project Id
        service_name:
          description: Service type. `postgresql` today.
          title: Service Name
          type: string
        status:
          anyOf:
            - type: string
            - type: 'null'
          description: Current connector status.
          title: Status
      required:
        - id
        - org_id
        - name
        - service_name
      title: ConnectorRow
      type: object
    OperationHandle:
      properties:
        operation_id:
          description: Operation to poll at `GET /v1/operations/{operation_id}`.
          title: Operation Id
          type: string
        resource_id:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            ID of the resource being created or acted on (the branch ID for
            branch create).
          title: Resource Id
        status:
          $ref: '#/components/schemas/OperationStatus'
          description: Status at acceptance time.
        type:
          $ref: '#/components/schemas/OperationType'
          description: The kind of work this operation tracks, for example `branch_create`.
      required:
        - operation_id
        - status
        - type
        - resource_id
      title: OperationHandle
      type: object
    OperationStatus:
      enum:
        - pending
        - running
        - completed
        - failed
      title: OperationStatus
      type: string
    OperationType:
      enum:
        - connector_engine_setup
```

--------------------------------

### ardent connector retry-setup

Source: https://docs.tryardent.com/cli/connectors

Attempts to finish or repair the setup of a connector while preserving existing credentials and configuration.

```APIDOC
## ardent connector retry-setup [name]

### Description
Retries the setup process for a connector. Behavior varies based on the current state (e.g., re-checking sources if stale, or joining an existing setup process).

### Parameters
- **name** (string) - Required - The name of the connector to retry.

### Options
- **--replica-identity-decisions** (path) - Optional - Path to a JSON file containing replica identity decisions.
- **--accept-replica-identity-defaults** (flag) - Optional - Accepts default replica identity settings.
```

--------------------------------

### Branch creation timeout error

Source: https://docs.tryardent.com/cli/branches

Example error message displayed when branch creation exceeds the 65-minute timeout.

```text
✗ Branch creation did not complete within 65 minutes. It may still be running server-side — do NOT assume it failed. Re-run the same command to resume, or check `ardent branch list`. If you contact Ardent support, reference operation id <operation-id>.
```

--------------------------------

### AI agent prompt for regression testing

Source: https://docs.tryardent.com/workflows/regression-testing

Example prompts to instruct an AI agent to perform regression testing using Ardent.

```text
Run a regression test on [describe change] against a real copy of our database.
```

```text
Run a regression test on [describe change] against a real copy of our database.
Create an Ardent branch (ardent branch create), run the tests against it,
report what broke, then delete the branch.
```

--------------------------------

### Check PlanetScale connection with AI agents

Source: https://docs.tryardent.com/connectors/planetscale

Use this prompt with Claude Code or Cursor if the Ardent CLI skill is installed.

```text
Check if my PlanetScale Postgres database is ready to connect to Ardent.
My connection string: [paste here]
```

--------------------------------

### Create a Database Connector

Source: https://docs.tryardent.com/quickstart

Initialize the connection to your database to enable branching.

```bash
ardent connector create postgresql "$ARDENT_DB_URL"
```

--------------------------------

### OpenAPI Specification for Get Branches

Source: https://docs.tryardent.com/api/branches/list

The OpenAPI definition for the GET /v1/branches/{connector_id} endpoint, including the BranchRow schema and bearer authentication requirements.

```yaml
openapi: 3.1.0
info:
  description: >-
    Public Ardent API. Generated by scripts/export_public_openapi.py — do not
    edit by hand.
  title: Ardent API
  version: v1
servers:
  - url: https://api.tryardent.com
security: []
paths:
  /v1/branches/{connector_id}:
    get:
      tags:
        - v1-branching
      summary: Get Branches
      operationId: get_branches_v1_branches__connector_id__get
      parameters:
        - in: path
          name: connector_id
          required: true
          schema:
            title: Connector Id
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                items:
                  $ref: '#/components/schemas/BranchRow'
                title: Response 200 Get Branches V1 Branches  Connector Id  Get
                type: array
          description: >-
            Up to 100 branch rows for the connector. Rows may carry additional
            columns beyond the documented core.
        '404':
          description: Connector not found (or not visible to the caller).
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      security:
        - bearerAuth: []
components:
  schemas:
    BranchRow:
      additionalProperties: true
      properties:
        branch_url:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            Direct connection URL for the branch; sensitive — use exactly as
            returned.
          title: Branch Url
        connector_id:
          description: Connector this branch was created from.
          title: Connector Id
          type: string
        created_at:
          description: When the branch was created.
          title: Created At
          type: string
        id:
          description: Branch ID.
          title: Id
          type: string
        last_branch_activity:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            Most recent activity on the branch. Null when none has been
            recorded.
          title: Last Branch Activity
        masked_ready_at:
          anyOf:
            - type: string
            - type: 'null'
          description: When masked data became ready. Null until then.
          title: Masked Ready At
        name:
          description: Branch name, as given at create.
          title: Name
          type: string
        pooled_branch_prisma_url:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            Prisma-formatted pooled URL; null when the provider has no pooled
            endpoint.
          title: Pooled Branch Prisma Url
        pooled_branch_url:
          anyOf:
            - type: string
            - type: 'null'
          description: >-
            Pooled connection URL. Null when the provider has no pooled
            endpoint.
          title: Pooled Branch Url
        read_ready_at:
          anyOf:
            - type: string
            - type: 'null'
          description: When the branch became ready for reads. Null until then.
          title: Read Ready At
        service_type:
          description: Branched service. `postgres` for Postgres branches.
          title: Service Type
          type: string
        status:
          description: Current branch status.
          title: Status
          type: string
        write_ready_at:
          anyOf:
            - type: string
            - type: 'null'
          description: When the branch became ready for writes. Null until then.
          title: Write Ready At
      required:
        - id
        - name
        - connector_id
        - service_type
        - status
        - created_at
      title: BranchRow
      type: object
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          title: Detail
          type: array
      title: HTTPValidationError
      type: object
    ValidationError:
      properties:
        ctx:
          title: Context
          type: object
        input:
          title: Input
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          title: Location
          type: array
        msg:
          title: Message
          type: string
        type:
          title: Error Type
          type: string
      required:
        - loc
        - msg
        - type
      title: ValidationError
      type: object
  securitySchemes:
    bearerAuth:
      description: >-
        Ardent API key (sk-ard_live_… / sk-ard_test_…) or a dashboard session
        token.
      scheme: bearer
      type: http
```

--------------------------------

### Get Project OpenAPI Specification

Source: https://docs.tryardent.com/api/projects/get

Defines the GET /v1/projects/{project_id} endpoint, including required parameters, response schemas, and bearer authentication requirements.

```yaml
openapi: 3.1.0
info:
  description: >-
    Public Ardent API. Generated by scripts/export_public_openapi.py — do not
    edit by hand.
  title: Ardent API
  version: v1
servers:
  - url: https://api.tryardent.com
security: []
paths:
  /v1/projects/{project_id}:
    get:
      tags:
        - v1-projects
      summary: Get Project Endpoint
      operationId: get_project_endpoint_v1_projects__project_id__get
      parameters:
        - in: path
          name: project_id
          required: true
          schema:
            title: Project Id
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectRow'
          description: Successful Response
        '404':
          description: Project not found (or not visible to the caller).
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      security:
        - bearerAuth: []
components:
  schemas:
    ProjectRow:
      additionalProperties: true
      properties:
        created_at:
          description: When the project was created.
          title: Created At
          type: string
        id:
          description: Project ID.
          title: Id
          type: string
        name:
          description: Project name.
          title: Name
          type: string
        org_id:
          description: Organization the project belongs to.
          title: Org Id
          type: string
      required:
        - id
        - org_id
        - name
        - created_at
      title: ProjectRow
      type: object
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          title: Detail
          type: array
      title: HTTPValidationError
      type: object
    ValidationError:
      properties:
        ctx:
          title: Context
          type: object
        input:
          title: Input
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          title: Location
          type: array
        msg:
          title: Message
          type: string
        type:
          title: Error Type
          type: string
      required:
        - loc
        - msg
        - type
      title: ValidationError
      type: object
  securitySchemes:
    bearerAuth:
      description: >-
        Ardent API key (sk-ard_live_… / sk-ard_test_…) or a dashboard session
        token.
      scheme: bearer
      type: http
```

--------------------------------

### Get Connector Endpoint OpenAPI Specification

Source: https://docs.tryardent.com/api/connectors/get

Defines the GET /v1/connectors/{connector_id} endpoint, including required parameters, response schemas, and security requirements.

```yaml
openapi: 3.1.0
info:
  description: >-
    Public Ardent API. Generated by scripts/export_public_openapi.py — do not
    edit by hand.
  title: Ardent API
  version: v1
servers:
  - url: https://api.tryardent.com
security: []
paths:
  /v1/connectors/{connector_id}:
    get:
      tags:
        - v1-connectors
      summary: Get Connector Endpoint
      operationId: get_connector_endpoint_v1_connectors__connector_id__get
      parameters:
        - in: path
          name: connector_id
          required: true
          schema:
            title: Connector Id
            type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectorRow'
          description: Successful Response
        '404':
          description: Connector not found (or not visible to the caller).
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
          description: Validation Error
      security:
        - bearerAuth: []
components:
  schemas:
    ConnectorRow:
      additionalProperties: true
      properties:
        can_delete:
          anyOf:
            - type: boolean
            - type: 'null'
          description: Whether the caller may delete this connector.
          title: Can Delete
        can_update:
          anyOf:
            - type: boolean
            - type: 'null'
          description: Whether the caller may update this connector.
          title: Can Update
        created_at:
          anyOf:
            - type: string
            - type: 'null'
          description: When the connector was created.
          title: Created At
        id:
          description: Connector ID.
          title: Id
          type: string
        name:
          description: Connector name.
          title: Name
          type: string
        org_id:
          description: Organization the connector belongs to.
          title: Org Id
          type: string
        project_id:
          anyOf:
            - type: string
            - type: 'null'
          description: Project the connector belongs to.
          title: Project Id
        service_name:
          description: Service type. `postgresql` today.
          title: Service Name
          type: string
        status:
          anyOf:
            - type: string
            - type: 'null'
          description: Current connector status.
          title: Status
      required:
        - id
        - org_id
        - name
        - service_name
      title: ConnectorRow
      type: object
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          title: Detail
          type: array
      title: HTTPValidationError
      type: object
    ValidationError:
      properties:
        ctx:
          title: Context
          type: object
        input:
          title: Input
        loc:
          items:
            anyOf:
              - type: string
              - type: integer
          title: Location
          type: array
        msg:
          title: Message
          type: string
        type:
          title: Error Type
          type: string
      required:
        - loc
        - msg
        - type
      title: ValidationError
      type: object
  securitySchemes:
    bearerAuth:
      description: >-
        Ardent API key (sk-ard_live_… / sk-ard_test_…) or a dashboard session
        token.
      scheme: bearer
      type: http
```

--------------------------------

### GET /v1/orgs/{org_id}/members

Source: https://docs.tryardent.com/api/orgs

List all members of an organization.

```APIDOC
## GET /v1/orgs/{org_id}/members

### Description
List members of the specified organization.

### Method
GET

### Endpoint
/v1/orgs/{org_id}/members

### Parameters
#### Path Parameters
- **org_id** (string) - Required - The unique identifier of the organization.
```

--------------------------------

### Access CLI Help

Source: https://docs.tryardent.com/cli/overview

Display help information for a specific command.

```bash
ardent branch create --help
```

--------------------------------

### GET /v1/orgs/{org_id}

Source: https://docs.tryardent.com/api/orgs

Retrieve details for a specific organization.

```APIDOC
## GET /v1/orgs/{org_id}

### Description
Get organization details.

### Method
GET

### Endpoint
/v1/orgs/{org_id}

### Parameters
#### Path Parameters
- **org_id** (string) - Required - The unique identifier of the organization.
```

--------------------------------

### GET /v1/connectors

Source: https://docs.tryardent.com/api/connectors/list

Retrieves a list of connectors for a given organization.

```APIDOC
## GET /v1/connectors

### Description
List an organization's connectors. Returns a list of connectors visible to the caller.

### Method
GET

### Endpoint
/v1/connectors

### Parameters
#### Query Parameters
- **org_id** (string) - Required - The ID of the organization.
- **connector_category** (string) - Optional - Filter by connector category.
- **service_name** (string) - Optional - Filter by service name.

### Response
#### Success Response (200)
- **connectors** (array) - List of connector objects.

#### Error Response (422)
- **detail** (array) - Validation error details.
```

--------------------------------

### GET /v1/projects

Source: https://docs.tryardent.com/api/projects

Retrieves a list of projects visible to the authenticated token.

```APIDOC
## GET /v1/projects

### Description
List projects visible to the token.

### Method
GET

### Endpoint
/v1/projects
```

--------------------------------

### Create a Database Branch

Source: https://docs.tryardent.com/quickstart

Create an isolated copy of your database.

```bash
ardent branch create my-feature
```

--------------------------------

### GET /v1/orgs/{org_id}/invites

Source: https://docs.tryardent.com/api/orgs

List all pending invitations for an organization.

```APIDOC
## GET /v1/orgs/{org_id}/invites

### Description
List pending invites for the organization.

### Method
GET

### Endpoint
/v1/orgs/{org_id}/invites

### Parameters
#### Path Parameters
- **org_id** (string) - Required - The unique identifier of the organization.
```

--------------------------------

### Run Database Preflight Check

Source: https://docs.tryardent.com/quickstart

Verify if the database is compatible with Ardent branching without storing credentials.

```bash
ardent connector preflight postgresql "$ARDENT_DB_URL"
```

--------------------------------

### Create a Database Branch

Source: https://docs.tryardent.com/cli/overview

Perform a preflight check before creating a connector and a new database branch.

```bash
ardent login
ardent connector preflight postgresql 'postgresql://user:***@host:5432/mydb'
ardent connector create postgresql 'postgresql://user:***@host:5432/mydb' --name prod-db
ardent branch create my-feature --print-url
```

--------------------------------

### Create a new Ardent project

Source: https://docs.tryardent.com/cli/projects

Initializes a new project and sets it as the current active project.

```bash
ardent project create <name>
```

```text
✓ Project 'staging' created
```

--------------------------------

### ardent connector status

Source: https://docs.tryardent.com/cli/connectors

Displays the health and setup progress of a specific connector.

```APIDOC
## ardent connector status [name]

### Description
Shows the health and setup progress for a specific connector identified by name.

### Parameters
- **name** (string) - Required - The name of the connector to check.
```

--------------------------------

### Switch CLI Context

Source: https://docs.tryardent.com/cli/overview

Manually set the active project, connector, or branch.

```bash
ardent project switch my-project
ardent connector switch prod-db
ardent branch switch my-feature
```

--------------------------------

### POST /v1/connectors/preflight

Source: https://docs.tryardent.com/api/connectors

Checks the readiness of a Postgres source server without creating a connector.

```APIDOC
## POST /v1/connectors/preflight

### Description
Checks source readiness without creating a connector.

### Method
POST

### Endpoint
/v1/connectors/preflight
```

--------------------------------

### GET /v1/projects

Source: https://docs.tryardent.com/api/projects/list

Retrieves a list of projects visible to the caller for a given organization.

```APIDOC
## GET /v1/projects

### Description
List projects visible to the token for a specific organization.

### Method
GET

### Endpoint
/v1/projects

### Parameters
#### Query Parameters
- **org_id** (string) - Required - The organization ID to filter projects by.

### Response
#### Success Response (200)
- **projects** (array) - List of projects visible to the caller.

#### Response Example
{
  "projects": [
    {
      "id": "string",
      "org_id": "string",
      "name": "string",
      "created_at": "string"
    }
  ]
}
```

--------------------------------

### GET /v1/orgs/{org_id}/roles

Source: https://docs.tryardent.com/api/orgs

List all available roles within an organization.

```APIDOC
## GET /v1/orgs/{org_id}/roles

### Description
List available roles.

### Method
GET

### Endpoint
/v1/orgs/{org_id}/roles

### Parameters
#### Path Parameters
- **org_id** (string) - Required - The unique identifier of the organization.
```

--------------------------------

### Create and manage an agent database branch via CLI

Source: https://docs.tryardent.com/workflows/ai-agents

Use this pattern to provision a database branch for an agent task and clean it up after execution. The agent receives the connection URL as an environment variable or prompt input.

```bash
# Create a branch for the agent task and capture its URL
AGENT_DATABASE_URL="$(ardent branch create agent-task --print-url)"
if [ -z "$AGENT_DATABASE_URL" ]; then
  echo "branch creation did not return a database URL" >&2
  exit 1
fi

# Hand the returned URL to your agent
# → $AGENT_DATABASE_URL

# Agent writes migrations, runs queries, tests against real data
# When it's done, clean up
ardent branch delete agent-task
```

--------------------------------

### GET /v1/connectors/{connector_id}

Source: https://docs.tryardent.com/api/connectors

Returns the status and readiness information for a specific connector.

```APIDOC
## GET /v1/connectors/{connector_id}

### Description
Returns status and readiness information.

### Method
GET

### Endpoint
/v1/connectors/{connector_id}

### Parameters
#### Path Parameters
- **connector_id** (string) - Required - The unique identifier of the connector.
```

--------------------------------

### GET /v1/branches/{connector_id}

Source: https://docs.tryardent.com/api/branches

Retrieves a list of all branches associated with a specific connector.

```APIDOC
## GET /v1/branches/{connector_id}

### Description
Lists all branches for a given connector.

### Method
GET

### Endpoint
/v1/branches/{connector_id}

### Parameters
#### Path Parameters
- **connector_id** (string) - Required - The unique identifier of the connector.
```

--------------------------------

### Configure private-network and customer-cloud connectors

Source: https://docs.tryardent.com/api/connectors/create

Use these parameters when creating a connector within a private network or customer-cloud environment. Ensure use_environment is set to true when providing environment and private link IDs.

```json
{
  "use_environment": true,
  "environment_id": "env_123",
  "private_link_id": "epl_123"
}
```

--------------------------------

### Create a branch with JSON output

Source: https://docs.tryardent.com/cli/configuration

Use the --format json flag to receive machine-readable output from branch creation commands.

```bash
ardent branch create pr-123 --format json
```

--------------------------------

### Create a database connector

Source: https://docs.tryardent.com/cli/connectors

Initializes a connection to a PostgreSQL database. Ensure the connection string is wrapped in single quotes to prevent shell interpretation of special characters.

```bash
ardent connector create postgresql 'postgresql://user:***@host:5432/mydb' --name prod-db
```

--------------------------------

### GET /v1/projects/{project_id}

Source: https://docs.tryardent.com/api/projects/get

Retrieves the details of a specific project identified by the provided project_id.

```APIDOC
## GET /v1/projects/{project_id}

### Description
Retrieves the details of a specific project identified by the provided project_id.

### Method
GET

### Endpoint
/v1/projects/{project_id}

### Parameters
#### Path Parameters
- **project_id** (string) - Required - The unique identifier of the project.

### Response
#### Success Response (200)
- **id** (string) - Project ID.
- **org_id** (string) - Organization the project belongs to.
- **name** (string) - Project name.
- **created_at** (string) - When the project was created.

#### Error Response (404)
- Project not found (or not visible to the caller).

#### Error Response (422)
- Validation Error
```

--------------------------------

### List Ardent projects and connectors

Source: https://docs.tryardent.com/workflows/ci-cd

Use these commands locally to identify the project and connector names required for CI configuration.

```bash
ardent project list
ardent connector list
```

--------------------------------

### GET /v1/branches/{connector_id}

Source: https://docs.tryardent.com/api/branches/list

Retrieves a list of up to 100 branch rows for a specified connector.

```APIDOC
## GET /v1/branches/{connector_id}

### Description
Retrieves a list of up to 100 branch rows for the specified connector. Rows may carry additional columns beyond the documented core.

### Method
GET

### Endpoint
/v1/branches/{connector_id}

### Parameters
#### Path Parameters
- **connector_id** (string) - Required - The ID of the connector to retrieve branches for.

### Response
#### Success Response (200)
- **Array of BranchRow** (array) - A list of branch objects.

#### Response Example
[
  {
    "id": "branch_123",
    "name": "main",
    "connector_id": "conn_abc",
    "service_type": "postgres",
    "status": "active",
    "created_at": "2023-01-01T00:00:00Z"
  }
]
```

--------------------------------

### Manage development branches

Source: https://docs.tryardent.com/workflows/local-dev

Create a branch, connect to its database URL, and delete it after completing tasks.

```bash
# Starting a new feature
ardent branch create my-feature

# Work, run migrations, break things freely
BRANCH_DATABASE_URL="$(ardent branch info --print-url)"
if [ -z "$BRANCH_DATABASE_URL" ]; then
  echo "branch info did not return a database URL" >&2
  exit 1
fi
psql "$BRANCH_DATABASE_URL"

# Done, or it all went wrong. Either way:
ardent branch delete my-feature
```

--------------------------------

### Get branch information

Source: https://docs.tryardent.com/cli/branches

Displays connection URLs and status for a specific branch or the current branch.

```bash
ardent branch info my-feature
```

```text
Branch: my-feature (current)
  Type:    postgres
  Status:  active
  Ready:   read + write
  Created: 6/1/2026, 12:00:00 PM

Direct URL: postgresql://user:***@my-feature-postgres.routing.tryardent.com:5432/db?sslmode=require&channel_binding=disable
```

```bash
ardent branch info --print-url
ardent branch info my-feature --format json
```

--------------------------------

### GET /operations/{operation_id}

Source: https://docs.tryardent.com/api/overview

Polls the status of a long-running operation initiated by an asynchronous API call.

```APIDOC
## GET /operations/{operation_id}

### Description
Retrieves the status of a long-running operation. Use this to poll for completion of tasks like branch creation.

### Method
GET

### Endpoint
https://api.tryardent.com/v1/operations/{operation_id}

### Parameters
#### Path Parameters
- **operation_id** (string) - Required - The unique identifier of the operation.
```

--------------------------------

### GitHub Actions configuration

Source: https://docs.tryardent.com/cli/auth

Example of using the ARDENT_TOKEN secret within a GitHub Actions workflow.

```yaml
env:
  ARDENT_TOKEN: ${{ secrets.ARDENT_TOKEN }}

steps:
  - run: npm install -g ardent-cli
  - run: ardent project switch my-project
  - run: ardent connector switch prod-db
  - run: echo "DATABASE_URL=$(ardent branch create pr-${{ github.run_id }} --print-url)" >> "$GITHUB_ENV"
```

--------------------------------

### List Ardent settings

Source: https://docs.tryardent.com/cli/settings

Displays the current configuration for Ardent settings.

```bash
ardent settings list
```

```text
Connector: prod-db
  default_db   myapp
  branch_sql   (not set)   SQL to run on every new branch after creation
```

--------------------------------

### List Ardent connectors

Source: https://docs.tryardent.com/cli/connectors

Displays all configured connectors and their current status.

```bash
ardent connector list
```

--------------------------------

### GET /v1/orgs

Source: https://docs.tryardent.com/api/orgs

List organizations. Note: This endpoint requires a dashboard session and does not accept API tokens.

```APIDOC
## GET /v1/orgs

### Description
List organizations associated with the current dashboard session.

### Method
GET

### Endpoint
/v1/orgs
```

--------------------------------

### Check Supabase connection readiness with AI

Source: https://docs.tryardent.com/connectors/supabase

Use these prompts with Claude Code or Cursor to verify your Supabase database configuration.

```text
Check if my Supabase database is ready to connect to Ardent.
My connection string: [paste here]
```

```text
Check if my Supabase database is ready to connect to Ardent.
My connection string: [paste here]

Use Ardent preflight first:
ardent connector preflight postgresql '<connection-string>' --schemas public

Verify:
1. This is the Direct connection string, not the pooler string.
2. IPv4 is enabled for the Supabase project.
3. The URL points to the writable primary: SELECT pg_is_in_recovery(); must return false.
4. Logical replication and wal2json are available.
5. The Ardent preflight Grant script has been run for the schemas I want to replicate.
6. Tables selected for replication have a primary key, valid unique NOT NULL index, or REPLICA IDENTITY FULL.

After preflight passes, run:
ardent connector create postgresql '<connection-string>'
```

--------------------------------

### GET /v1/connectors/{connector_id}

Source: https://docs.tryardent.com/api/connectors/get

Retrieves detailed information about a specific connector, including its status and user permissions.

```APIDOC
## GET /v1/connectors/{connector_id}

### Description
Inspect a connector's status and readiness. Returns status and readiness information, plus `can_update` and `can_delete` permission flags for the calling token.

### Method
GET

### Endpoint
/v1/connectors/{connector_id}

### Parameters
#### Path Parameters
- **connector_id** (string) - Required - The unique identifier of the connector.

### Response
#### Success Response (200)
- **id** (string) - Connector ID.
- **org_id** (string) - Organization the connector belongs to.
- **name** (string) - Connector name.
- **service_name** (string) - Service type (e.g., postgresql).
- **status** (string|null) - Current connector status.
- **created_at** (string|null) - When the connector was created.
- **project_id** (string|null) - Project the connector belongs to.
- **can_update** (boolean|null) - Whether the caller may update this connector.
- **can_delete** (boolean|null) - Whether the caller may delete this connector.
```