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

# Examples

> Curl examples for common API operations

This page provides practical curl examples for interacting with the Pragmatiks API.

## Setup

Set your authentication token as an environment variable:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
export TOKEN=$(pragma auth token)
export API="https://api.pragmatiks.io"
```

## Resources

### List All Resources

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
curl -H "Authorization: Bearer $TOKEN" \
  "$API/resources/"
```

**Response:**

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
[
  {
    "provider": "postgres",
    "resource": "database",
    "name": "my-app-db",
    "lifecycle_state": "ready",
    "config": {
      "version": "15"
    },
    "outputs": {
      "connection_string": "postgres://..."
    },
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-01-15T10:35:00Z"
  }
]
```

### Filter Resources by Provider

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

### Filter Resources by Type

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
curl -H "Authorization: Bearer $TOKEN" \
  "$API/resources/?provider=postgres&resource=database"
```

### Filter Resources by Tags

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

### Get a Specific Resource

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
curl -H "Authorization: Bearer $TOKEN" \
  "$API/resources/postgres%3Adatabase%3Amy-app-db"
```

<Note>
  Resource IDs use the format `provider:resource:name` and must be URL-encoded. The colon `:` becomes `%3A`.
</Note>

### Create a Resource (Draft)

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  "$API/resources/apply" \
  -d '{
    "provider": "postgres",
    "resource": "database",
    "name": "my-new-db",
    "config": {
      "version": "15"
    },
    "lifecycle_state": "draft"
  }'
```

**Response:**

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "provider": "postgres",
  "resource": "database",
  "name": "my-new-db",
  "lifecycle_state": "draft",
  "config": {
    "version": "15"
  },
  "outputs": {},
  "created_at": "2025-01-15T11:00:00Z",
  "updated_at": "2025-01-15T11:00:00Z"
}
```

### Commit a Resource (Submit for Processing)

Change `lifecycle_state` to `pending` to submit the resource for processing:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  "$API/resources/apply" \
  -d '{
    "provider": "postgres",
    "resource": "database",
    "name": "my-new-db",
    "config": {
      "version": "15"
    },
    "lifecycle_state": "pending"
  }'
```

### Update an Existing Resource

Apply changes to an existing resource:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  "$API/resources/apply" \
  -d '{
    "provider": "postgres",
    "resource": "database",
    "name": "my-new-db",
    "config": {
      "version": "16"
    },
    "lifecycle_state": "pending"
  }'
```

### Delete a Resource

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
curl -X DELETE \
  -H "Authorization: Bearer $TOKEN" \
  "$API/resources/postgres%3Adatabase%3Amy-new-db"
```

**Response:** `204 No Content`

## Dead Letter Operations

### List Dead Letter Events

Events that failed processing are stored in the dead letter queue:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
curl -H "Authorization: Bearer $TOKEN" \
  "$API/ops/dead-letter"
```

**Response:**

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
[
  {
    "event_id": "evt_abc123",
    "provider": "postgres",
    "resource_type": "database",
    "resource_name": "failed-db",
    "event_type": "CREATE",
    "error_message": "Connection timeout",
    "attempt_count": 3,
    "failed_at": "2025-01-15T12:00:00Z"
  }
]
```

### Filter by Provider

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
curl -H "Authorization: Bearer $TOKEN" \
  "$API/ops/dead-letter?provider=postgres"
```

### Get a Specific Dead Letter Event

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
curl -H "Authorization: Bearer $TOKEN" \
  "$API/ops/dead-letter/evt_abc123"
```

### Retry a Failed Event

Requeue a single event for processing:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  "$API/ops/dead-letter/evt_abc123/retry"
```

### Retry All Failed Events

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  "$API/ops/dead-letter/retry-all"
```

**Response:**

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "retried": 5
}
```

### Delete a Dead Letter Event

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
curl -X DELETE \
  -H "Authorization: Bearer $TOKEN" \
  "$API/ops/dead-letter/evt_abc123"
```

### Bulk Delete Dead Letter Events

Delete all events:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
curl -X DELETE \
  -H "Authorization: Bearer $TOKEN" \
  "$API/ops/dead-letter?all=true"
```

Delete events for a specific provider:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
curl -X DELETE \
  -H "Authorization: Bearer $TOKEN" \
  "$API/ops/dead-letter?provider=postgres"
```

## Provider Operations

### Push Provider Code

Upload provider code to start a build:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -F "code=@provider.tar.gz" \
  "$API/providers/my-provider/push"
```

**Response:**

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "version": "20250115.120000",
  "job_name": "build-my-provider-abc123",
  "status": "pending",
  "message": "Build job created"
}
```

### Check Build Status

Poll the build status until completion:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
curl -H "Authorization: Bearer $TOKEN" \
  "$API/providers/my-provider/builds/build-my-provider-abc123"
```

**Response (in progress):**

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "job_name": "build-my-provider-abc123",
  "status": "building",
  "error_message": null
}
```

**Response (success):**

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "job_name": "build-my-provider-abc123",
  "status": "success",
  "error_message": null
}
```

### Stream Build Logs

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
curl -H "Authorization: Bearer $TOKEN" \
  "$API/providers/my-provider/builds/build-my-provider-abc123/logs"
```

### Deploy a Provider

Deploy the provider to a specific version (or latest if omitted):

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  "$API/providers/my-provider/deploy" \
  -d '{
    "version": "20250115.120000"
  }'
```

**Response:**

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "deployment_name": "provider-my-provider",
  "status": "progressing",
  "available_replicas": 0,
  "ready_replicas": 0
}
```

### Check Deployment Status

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
curl -H "Authorization: Bearer $TOKEN" \
  "$API/providers/my-provider/deployment"
```

**Response (available):**

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "deployment_name": "provider-my-provider",
  "status": "available",
  "available_replicas": 1,
  "ready_replicas": 1
}
```

## Resource Definitions

### Register a Resource Type

Providers register resource types to declare what they can manage:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  "$API/resources/register" \
  -d '{
    "provider": "my-provider",
    "resource": "widget",
    "description": "A custom widget resource",
    "schema": {
      "type": "object",
      "properties": {
        "size": {"type": "string"},
        "color": {"type": "string"}
      },
      "required": ["size"]
    }
  }'
```

### Unregister a Resource Type

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
curl -X DELETE \
  -H "Authorization: Bearer $TOKEN" \
  "$API/resources/unregister/my-provider/widget"
```

## Health Check

The health endpoint does not require authentication:

```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
curl "$API/health"
```

**Response:**

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "status": "healthy"
}
```