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

# API Reference

> Pragmatiks REST API reference and overview

The Pragmatiks API provides programmatic access to all platform features. Use it to manage resources, monitor operations, and deploy providers.

## Base URL

```
https://api.pragmatiks.io
```

## Authentication

All API endpoints except `/health` require authentication using Bearer tokens.

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
curl -H "Authorization: Bearer <token>" \
  https://api.pragmatiks.io/resources/
```

Get a token by running `pragma auth login` or through the web dashboard. See [Authentication](/api-reference/authentication) for details.

## Request Format

* Use `Content-Type: application/json` for JSON request bodies
* Use `multipart/form-data` for file uploads (e.g., provider code)
* All timestamps use ISO 8601 format in UTC

## Response Format

Successful responses return JSON. List endpoints return arrays:

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
[
  {"provider": "postgres", "resource": "database", "name": "my-db", ...}
]
```

Single-resource endpoints return objects:

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{"provider": "postgres", "resource": "database", "name": "my-db", ...}
```

## Filtering

List endpoints support filtering via query parameters:

| Endpoint               | Parameters                     |
| ---------------------- | ------------------------------ |
| `GET /resources/`      | `provider`, `resource`, `tags` |
| `GET /ops/dead-letter` | `provider`                     |

### Examples

Filter resources by provider:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
curl -H "Authorization: Bearer $TOKEN" \
  "https://api.pragmatiks.io/resources/?provider=postgres"
```

Filter resources by multiple tags (all must match):

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
curl -H "Authorization: Bearer $TOKEN" \
  "https://api.pragmatiks.io/resources/?tags=production&tags=critical"
```

## Resource Identifiers

Resources are identified by a prefixed ID format: `resource:{provider}_{resource}_{name}`. When used in URLs, this must be URL-encoded:

| Component   | Example                                 |
| ----------- | --------------------------------------- |
| Format      | `resource:{provider}_{resource}_{name}` |
| Unencoded   | `resource:postgres_database_my-db`      |
| URL-encoded | `resource%3Apostgres_database_my-db`    |

<Note>
  The CLI and YAML files use a friendlier slash notation (`provider/resource/name`), which the API translates to the internal ID format.
</Note>

## Lifecycle States

Resources follow a 5-state lifecycle:

| State        | Description                                        |
| ------------ | -------------------------------------------------- |
| `draft`      | Initial state, can be modified freely              |
| `pending`    | Committed for processing, no modifications allowed |
| `processing` | Being handled by a provider                        |
| `ready`      | Successfully processed                             |
| `failed`     | Processing failed, error recorded                  |

Set `lifecycle_state` when applying a resource:

* `draft` - Store without processing (default)
* `pending` - Validate and queue for processing

## Rate Limits

API requests are rate limited per organization. Contact support if you need higher limits.

## OpenAPI Specification

The full API specification is available in OpenAPI 3.1 format. Use it to generate client libraries or explore endpoints.

## Next Steps

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/api-reference/authentication">
    Learn how to authenticate API requests.
  </Card>

  <Card title="Error Codes" icon="triangle-exclamation" href="/api-reference/errors">
    Understand error responses and status codes.
  </Card>

  <Card title="Examples" icon="code" href="/api-reference/examples">
    See curl examples for common operations.
  </Card>

  <Card title="CLI Reference" icon="terminal" href="/cli/overview">
    Use the CLI for easier interaction with the API.
  </Card>
</CardGroup>