Examples - Pragmatiks

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"
}

​Setup

​Resources

​List All Resources

​Filter Resources by Provider

​Filter Resources by Type

​Filter Resources by Tags

​Get a Specific Resource

​Create a Resource (Draft)

​Commit a Resource (Submit for Processing)

​Update an Existing Resource

​Delete a Resource

​Dead Letter Operations

​List Dead Letter Events

​Filter by Provider

​Get a Specific Dead Letter Event

​Retry a Failed Event

​Retry All Failed Events

​Delete a Dead Letter Event

​Bulk Delete Dead Letter Events

​Provider Operations

​Push Provider Code

​Check Build Status

​Stream Build Logs

​Deploy a Provider

​Check Deployment Status

​Resource Definitions

​Register a Resource Type

​Unregister a Resource Type

​Health Check

Setup

Resources

List All Resources

Filter Resources by Provider

Filter Resources by Type

Filter Resources by Tags

Get a Specific Resource

Create a Resource (Draft)

Commit a Resource (Submit for Processing)

Update an Existing Resource

Delete a Resource

Dead Letter Operations

List Dead Letter Events

Filter by Provider

Get a Specific Dead Letter Event

Retry a Failed Event

Retry All Failed Events

Delete a Dead Letter Event

Bulk Delete Dead Letter Events

Provider Operations

Push Provider Code

Check Build Status

Stream Build Logs

Deploy a Provider

Check Deployment Status

Resource Definitions

Register a Resource Type

Unregister a Resource Type

Health Check