Skip to main content

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.

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

​
Setup

Set your authentication token as an environment variable: 
export TOKEN=$(pragma auth token)
export API="https://api.pragmatiks.io"

​
Resources

​
List All Resources

curl -H "Authorization: Bearer $TOKEN" \
  "$API/resources/"
Response: 
[
  {
    "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

curl -H "Authorization: Bearer $TOKEN" \
  "$API/resources/?provider=postgres"

​
Filter Resources by Type

curl -H "Authorization: Bearer $TOKEN" \
  "$API/resources/?provider=postgres&resource=database"

​
Filter Resources by Tags

curl -H "Authorization: Bearer $TOKEN" \
  "$API/resources/?tags=production&tags=critical"

​
Get a Specific Resource

curl -H "Authorization: Bearer $TOKEN" \
  "$API/resources/postgres%3Adatabase%3Amy-app-db"
Resource IDs use the format provider:resource:name and must be URL-encoded. The colon : becomes %3A.

​
Create a Resource (Draft)

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: 
{
  "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: 
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: 
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

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: 
curl -H "Authorization: Bearer $TOKEN" \
  "$API/ops/dead-letter"
Response: 
[
  {
    "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

curl -H "Authorization: Bearer $TOKEN" \
  "$API/ops/dead-letter?provider=postgres"

​
Get a Specific Dead Letter Event

curl -H "Authorization: Bearer $TOKEN" \
  "$API/ops/dead-letter/evt_abc123"

​
Retry a Failed Event

Requeue a single event for processing: 
curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  "$API/ops/dead-letter/evt_abc123/retry"

​
Retry All Failed Events

curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  "$API/ops/dead-letter/retry-all"
Response: 
{
  "retried": 5
}

​
Delete a Dead Letter Event

curl -X DELETE \
  -H "Authorization: Bearer $TOKEN" \
  "$API/ops/dead-letter/evt_abc123"

​
Bulk Delete Dead Letter Events

Delete all events: 
curl -X DELETE \
  -H "Authorization: Bearer $TOKEN" \
  "$API/ops/dead-letter?all=true"
Delete events for a specific provider: 
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: 
curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -F "code=@provider.tar.gz" \
  "$API/providers/my-provider/push"
Response: 
{
  "version": "20250115.120000",
  "job_name": "build-my-provider-abc123",
  "status": "pending",
  "message": "Build job created"
}

​
Check Build Status

Poll the build status until completion: 
curl -H "Authorization: Bearer $TOKEN" \
  "$API/providers/my-provider/builds/build-my-provider-abc123"
Response (in progress): 
{
  "job_name": "build-my-provider-abc123",
  "status": "building",
  "error_message": null
}
Response (success): 
{
  "job_name": "build-my-provider-abc123",
  "status": "success",
  "error_message": null
}

​
Stream Build Logs

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): 
curl -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  "$API/providers/my-provider/deploy" \
  -d '{
    "version": "20250115.120000"
  }'
Response: 
{
  "deployment_name": "provider-my-provider",
  "status": "progressing",
  "available_replicas": 0,
  "ready_replicas": 0
}

​
Check Deployment Status

curl -H "Authorization: Bearer $TOKEN" \
  "$API/providers/my-provider/deployment"
Response (available): 
{
  "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: 
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

curl -X DELETE \
  -H "Authorization: Bearer $TOKEN" \
  "$API/resources/unregister/my-provider/widget"

​
Health Check

The health endpoint does not require authentication: 
curl "$API/health"
Response: 
{
  "status": "healthy"
}