Create account
GridRuns API v1

Send real-world tasks from software.

The Programmer API lets software act on behalf of a regular GridRuns account. Create funded tasks, track their state, retrieve submitted results, and confirm or dispute the work. Administrative and mediator-only capabilities are not exposed.

Base URL

https://www.gridruns.com/api/v1

All authenticated requests use a personal API key as a bearer token.

Core guarantees

  • Revocable API keys, stored hashed by GridRuns.
  • Idempotent task creation.
  • Caller-defined external references.
  • Stable JSON errors and versioned routes.

1. Create an API key

The secret is returned once. Store it in a secret manager and do not commit it to source control.

curl -X POST https://www.gridruns.com/api/v1/auth/tokens \
  -H 'Content-Type: application/json' \
  -d '{
    "email": "platform@example.com",
    "password": "your-password",
    "name": "Production integration"
  }'

Authenticate subsequent calls

Authorization: Bearer gr_your_api_key

2. Create an idempotent task

Every creation request requires an Idempotency-Key. Retrying the same JSON body with the same key returns the original task. Reusing a key with a different body returns HTTP 409.

curl -X POST https://www.gridruns.com/api/v1/tasks \
  -H 'Authorization: Bearer gr_your_api_key' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: parking-42-check-1001' \
  -d '{
    "external_reference": "parking-42/check-1001",
    "title": "Parking availability check",
    "instructions": "Report none, 1-2 spaces, or 3+ spaces and attach a current photo.",
    "execution_scope": "local",
    "credits_cents": 500,
    "currency": "CRD",
    "performance_bond_cents": 0,
    "mediation_bond_cents": 0,
    "location": {
      "label": "Parking Example",
      "city": "Bucharest",
      "region": "Bucharest",
      "country": "RO",
      "latitude": 44.443809,
      "longitude": 26.130558,
      "radius_meters": 100
    },
    "result_requirements": [
      "Report none, 1-2 spaces, or 3+ spaces.",
      "Attach a current photograph of the parking area."
    ]
  }'

Result requirements are currently instructions for the runner. Clients that require a photograph should verify that result.attachments is non-empty and that the result is interpretable before confirming the task. Use request-revision to ask for clarification while keeping Intel offered in escrow, then read the runner's answer from messages.

Endpoints

POST/auth/tokens
GET/auth/tokens
DELETE/auth/tokens/{id}
GET/account
GET/wallet
POST/tasks
GET/tasks
GET/tasks/{id}
POST/tasks/{id}/confirm
GET/tasks/{id}/messages
POST/tasks/{id}/request-revision
POST/tasks/{id}/dispute
POST/tasks/{id}/cancel
GET/attachments/{id}

For request and response schemas, import the public OpenAPI specification linked above.

Errors

{
  "error": {
    "code": "validation_error",
    "message": "The request is invalid.",
    "details": {
      "credits_cents": ["The Intel offered field is required."]
    }
  }
}