{
  "openapi": "3.1.0",
  "info": {
    "title": "Colter purchased jobs \u2014 approved-account pilot",
    "version": "2026-09-10",
    "description": "Supported account purchase and customer-review flow. This is a subset of the Colter API; legacy and wallet endpoints remain separate. Contact the pilot team for service availability, credentials, sources and agreed terms.",
    "contact": {
      "email": "hello@colter.ai"
    }
  },
  "servers": [
    {
      "url": "https://api.colter.ai",
      "description": "Approved-account pilot"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "paths": {
    "/api/v2/services": {
      "get": {
        "operationId": "listServices",
        "summary": "Discover services available to this workspace",
        "description": "Discover services available to this workspace",
        "x-colter-scope": "services:read",
        "parameters": [
          {
            "name": "X-Colter-Workspace",
            "in": "header",
            "required": true,
            "description": "Approved workspace slug. Account and access are resolved from the authenticated token.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "services": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Service"
                      }
                    }
                  },
                  "required": [
                    "services"
                  ]
                }
              }
            }
          },
          "default": {
            "description": "Authentication, permission, conflict, funding, or validation error. See the error code and message; do not retry a purchase with a new key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v2/services/{service_key}": {
      "get": {
        "operationId": "getService",
        "summary": "Inspect the current service contract",
        "description": "Inspect the current service contract",
        "x-colter-scope": "services:read",
        "parameters": [
          {
            "name": "X-Colter-Workspace",
            "in": "header",
            "required": true,
            "description": "Approved workspace slug. Account and access are resolved from the authenticated token.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "service_key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "service": {
                      "$ref": "#/components/schemas/Service"
                    }
                  },
                  "required": [
                    "service"
                  ]
                }
              }
            }
          },
          "default": {
            "description": "Authentication, permission, conflict, funding, or validation error. See the error code and message; do not retry a purchase with a new key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v2/jobs/purchase": {
      "post": {
        "operationId": "purchaseJob",
        "summary": "Purchase one job within delegated spending authority",
        "description": "Persist the key and exact payload before sending. Returns a job when auto-authorized, otherwise a quote with job null. A transport timeout does not cancel work. Resume with the same payload/key; changed fields produce a conflict. The example ceiling is not an advertised price. Required case/account/policy sources must be configured for the pilot.",
        "x-colter-scope": "quotes:write",
        "parameters": [
          {
            "name": "X-Colter-Workspace",
            "in": "header",
            "required": true,
            "description": "Approved workspace slug. Account and access are resolved from the authenticated token.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Transaction"
                },
                "example": {
                  "disposition": "created",
                  "quote": {
                    "quote_key": "quote_example",
                    "status": "requested",
                    "service": {
                      "key": "support_case_investigation",
                      "version": 1
                    },
                    "price": {
                      "amount_microcents": 200000000,
                      "currency": "USD"
                    },
                    "context": {
                      "schema_version": "colter.context_manifest.v1",
                      "refs": []
                    },
                    "expires_at": "2026-09-10T15:00:00Z"
                  },
                  "job": null
                }
              }
            }
          },
          "201": {
            "description": "First auto-authorized purchase",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Transaction"
                }
              }
            }
          },
          "409": {
            "description": "Conflicting reuse of a key or expired quote",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "conflict",
                    "message": "Idempotency key was reused."
                  }
                }
              }
            }
          },
          "422": {
            "description": "Invalid input, service version, missing price ceiling, or price above ceiling",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "default": {
            "description": "Authentication, permission, conflict, funding, or validation error. See the error code and message; do not retry a purchase with a new key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Purchase"
              },
              "example": {
                "service_key": "support_case_investigation",
                "service_version": 1,
                "input_payload": {
                  "question": "What is the appropriate next step for case 42?"
                },
                "idempotency_key": "caller-case-42-investigation-1",
                "max_price_microcents": 200000000,
                "correlation_id": "caller-case-42",
                "context_refs": []
              }
            }
          }
        }
      }
    },
    "/api/v2/quotes": {
      "post": {
        "operationId": "requestQuote",
        "summary": "Request a quote without starting work",
        "description": "Request a quote without starting work",
        "x-colter-scope": "quotes:write",
        "parameters": [
          {
            "name": "X-Colter-Workspace",
            "in": "header",
            "required": true,
            "description": "Approved workspace slug. Account and access are resolved from the authenticated token.",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Transaction"
                }
              }
            }
          },
          "201": {
            "description": "New quote",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Transaction"
                }
              }
            }
          },
          "default": {
            "description": "Authentication, permission, conflict, funding, or validation error. See the error code and message; do not retry a purchase with a new key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/QuoteRequest"
              },
              "example": {
                "service_key": "support_case_investigation",
                "service_version": 1,
                "input_payload": {
                  "question": "What is the appropriate next step for case 42?"
                },
                "idempotency_key": "caller-case-42-investigation-1",
                "max_price_microcents": 200000000,
                "correlation_id": "caller-case-42",
                "context_refs": [],
                "auto_accept": false
              }
            }
          }
        }
      }
    },
    "/api/v2/quotes/{quote_key}": {
      "get": {
        "operationId": "getQuote",
        "summary": "Inspect quote terms and expiry",
        "description": "Inspect quote terms and expiry",
        "x-colter-scope": "quotes:read",
        "parameters": [
          {
            "name": "X-Colter-Workspace",
            "in": "header",
            "required": true,
            "description": "Approved workspace slug. Account and access are resolved from the authenticated token.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "quote_key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "quote": {
                      "$ref": "#/components/schemas/Quote"
                    }
                  },
                  "required": [
                    "quote"
                  ]
                }
              }
            }
          },
          "default": {
            "description": "Authentication, permission, conflict, funding, or validation error. See the error code and message; do not retry a purchase with a new key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v2/quotes/{quote_key}/accept": {
      "post": {
        "operationId": "acceptQuote",
        "summary": "Accept the quoted scope and price",
        "description": "Requires appropriate delegated spend authority or an authorized workspace manager. Acceptance starts the purchased job; do not accept expired or unreviewed terms.",
        "x-colter-scope": "quotes:write",
        "parameters": [
          {
            "name": "X-Colter-Workspace",
            "in": "header",
            "required": true,
            "description": "Approved workspace slug. Account and access are resolved from the authenticated token.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "quote_key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Transaction"
                }
              }
            }
          },
          "default": {
            "description": "Authentication, permission, conflict, funding, or validation error. See the error code and message; do not retry a purchase with a new key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v2/jobs/{job_key}": {
      "get": {
        "operationId": "getJob",
        "summary": "Observe durable job and execution state",
        "description": "Observe durable job and execution state",
        "x-colter-scope": "jobs:read",
        "parameters": [
          {
            "name": "X-Colter-Workspace",
            "in": "header",
            "required": true,
            "description": "Approved workspace slug. Account and access are resolved from the authenticated token.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "job_key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "job": {
                      "$ref": "#/components/schemas/Job"
                    }
                  },
                  "required": [
                    "job"
                  ]
                }
              }
            }
          },
          "default": {
            "description": "Authentication, permission, conflict, funding, or validation error. See the error code and message; do not retry a purchase with a new key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v2/jobs/{job_key}/outcome": {
      "get": {
        "operationId": "getOutcome",
        "summary": "Retrieve result, evidence, customer resolution and charge",
        "description": "Execution completion is separate from customer acceptance and collection. Poll this route after interruption. Customer-reviewed pilot work remains advisory. A finalized charge is not proof that payment was collected.",
        "x-colter-scope": "jobs:read",
        "parameters": [
          {
            "name": "X-Colter-Workspace",
            "in": "header",
            "required": true,
            "description": "Approved workspace slug. Account and access are resolved from the authenticated token.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "job_key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "outcome": {
                      "$ref": "#/components/schemas/Outcome"
                    }
                  },
                  "required": [
                    "outcome"
                  ]
                },
                "example": {
                  "outcome": {
                    "job_key": "job_example",
                    "status": "completed",
                    "resolution_state": "in_review",
                    "resolution_verdict": null,
                    "submission": {
                      "id": 1,
                      "result_payload": {
                        "recommendation": "Request manager review of the earlier refund promise."
                      }
                    },
                    "resolution": null,
                    "result": {
                      "recommendation": "Request manager review of the earlier refund promise.",
                      "checked_result": false,
                      "requires_human_review": true
                    },
                    "evidence": {
                      "events": [],
                      "context": {
                        "refs": []
                      }
                    },
                    "charge": {
                      "status": "pending",
                      "currency": "USD",
                      "agreed_price_microcents": 200000000,
                      "final_charge_microcents": null,
                      "finalized_at": null
                    },
                    "delivery": {
                      "correlation_id": "caller-case-42"
                    }
                  }
                }
              }
            }
          },
          "402": {
            "description": "Some payment lanes require settlement. Customer-reviewed pilot eligibility and account terms apply.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          },
          "default": {
            "description": "Authentication, permission, conflict, funding, or validation error. See the error code and message; do not retry a purchase with a new key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/api/v2/jobs/{job_key}/submissions/{submission_id}/resolution": {
      "post": {
        "operationId": "reviewDelivery",
        "summary": "Record the authorized customer's review",
        "description": "Use only the designated reviewer's identity and the submission ID from the outcome. A machine's purchasing token does not confer customer-review authority. Acceptance can finalize the agreed charge; inconclusive requires attention. Rejection follows the service's remedy terms.",
        "x-colter-scope": "jobs:write",
        "parameters": [
          {
            "name": "X-Colter-Workspace",
            "in": "header",
            "required": true,
            "description": "Approved workspace slug. Account and access are resolved from the authenticated token.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "job_key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "submission_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Customer resolution recorded",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "resolution": {
                      "type": "object"
                    }
                  },
                  "required": [
                    "resolution"
                  ]
                }
              }
            }
          },
          "default": {
            "description": "Authentication, permission, conflict, funding, or validation error. See the error code and message; do not retry a purchase with a new key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Review"
              }
            }
          }
        }
      }
    },
    "/api/v2/jobs/{job_key}/ledger": {
      "get": {
        "operationId": "getJobLedger",
        "summary": "Inspect financial events and reconciliation",
        "description": "Inspect financial events and reconciliation",
        "x-colter-scope": "jobs:read",
        "parameters": [
          {
            "name": "X-Colter-Workspace",
            "in": "header",
            "required": true,
            "description": "Approved workspace slug. Account and access are resolved from the authenticated token.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "job_key",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Successful response",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "summary": {
                      "type": "object"
                    },
                    "events": {
                      "type": "array",
                      "items": {
                        "type": "object"
                      }
                    }
                  },
                  "required": [
                    "summary",
                    "events"
                  ]
                }
              }
            }
          },
          "default": {
            "description": "Authentication, permission, conflict, funding, or validation error. See the error code and message; do not retry a purchase with a new key.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Scoped Colter account token. Never include tokens in job input or shared collections."
      }
    },
    "schemas": {
      "Service": {
        "type": "object",
        "properties": {
          "service_key": {
            "type": "string"
          },
          "version": {
            "type": "integer"
          },
          "name": {
            "type": "string"
          },
          "input_schema": {
            "type": "object"
          },
          "output_schema": {
            "type": "object"
          },
          "billing_trigger": {
            "type": "string"
          },
          "price": {
            "$ref": "#/components/schemas/Money"
          },
          "acceptance_criteria": {
            "type": "array",
            "items": {
              "type": "string"
            }
          }
        },
        "required": [
          "service_key",
          "version",
          "name",
          "input_schema",
          "output_schema",
          "billing_trigger",
          "price",
          "acceptance_criteria"
        ]
      },
      "Money": {
        "type": "object",
        "properties": {
          "amount_microcents": {
            "type": "integer"
          },
          "currency": {
            "type": "string"
          }
        },
        "required": [
          "amount_microcents",
          "currency"
        ]
      },
      "Job": {
        "type": "object",
        "properties": {
          "job_key": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "service": {
            "type": "object"
          },
          "correlation_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "latest_run": {
            "type": "object"
          },
          "charge": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/Charge"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "job_key",
          "status",
          "service",
          "correlation_id",
          "latest_run",
          "charge"
        ]
      },
      "Quote": {
        "type": "object",
        "properties": {
          "quote_key": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "service": {
            "type": "object"
          },
          "price": {
            "$ref": "#/components/schemas/Money"
          },
          "context": {
            "type": "object"
          },
          "expires_at": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "quote_key",
          "status",
          "service",
          "price",
          "context",
          "expires_at"
        ]
      },
      "Charge": {
        "type": "object",
        "properties": {
          "status": {
            "type": "string"
          },
          "currency": {
            "type": "string"
          },
          "agreed_price_microcents": {
            "type": "integer"
          },
          "final_charge_microcents": {
            "type": [
              "integer",
              "null"
            ]
          },
          "finalized_at": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "status",
          "currency",
          "agreed_price_microcents",
          "final_charge_microcents",
          "finalized_at"
        ]
      },
      "Transaction": {
        "type": "object",
        "properties": {
          "disposition": {
            "type": "string"
          },
          "quote": {
            "$ref": "#/components/schemas/Quote"
          },
          "job": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/Job"
              },
              {
                "type": "null"
              }
            ]
          }
        },
        "required": [
          "disposition",
          "quote",
          "job"
        ]
      },
      "Outcome": {
        "type": "object",
        "properties": {
          "job_key": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "resolution_state": {
            "type": [
              "string",
              "null"
            ]
          },
          "resolution_verdict": {
            "type": [
              "string",
              "null"
            ]
          },
          "submission": {
            "type": [
              "object",
              "null"
            ]
          },
          "resolution": {
            "type": [
              "object",
              "null"
            ]
          },
          "result": {},
          "evidence": {
            "type": [
              "object",
              "null"
            ]
          },
          "charge": {
            "anyOf": [
              {
                "$ref": "#/components/schemas/Charge"
              },
              {
                "type": "null"
              }
            ]
          },
          "delivery": {
            "type": [
              "object",
              "null"
            ]
          }
        },
        "required": [
          "job_key",
          "status",
          "resolution_state",
          "resolution_verdict",
          "submission",
          "resolution",
          "result",
          "evidence",
          "charge",
          "delivery"
        ]
      },
      "Error": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            },
            "required": [
              "code",
              "message"
            ]
          }
        },
        "required": [
          "error"
        ]
      },
      "Purchase": {
        "type": "object",
        "properties": {
          "service_key": {
            "type": "string",
            "minLength": 1
          },
          "service_version": {
            "type": "integer",
            "minimum": 1
          },
          "input_payload": {
            "type": "object"
          },
          "idempotency_key": {
            "type": "string",
            "minLength": 1
          },
          "max_price_microcents": {
            "type": "integer",
            "minimum": 0,
            "description": "Caller ceiling; USD 1 = 100000000 microcents. Not a service price."
          },
          "context_refs": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "Preconfigured authorized connection references. Source endpoints and credentials belong to the registration, not this payload."
          },
          "correlation_id": {
            "type": "string",
            "description": "Opaque caller work ID. Included in the immutable purchase digest; does not establish identity or authority."
          }
        },
        "required": [
          "service_key",
          "input_payload",
          "idempotency_key",
          "max_price_microcents"
        ]
      },
      "QuoteRequest": {
        "type": "object",
        "properties": {
          "service_key": {
            "type": "string",
            "minLength": 1
          },
          "service_version": {
            "type": "integer",
            "minimum": 1
          },
          "input_payload": {
            "type": "object"
          },
          "idempotency_key": {
            "type": "string",
            "minLength": 1
          },
          "max_price_microcents": {
            "type": "integer",
            "minimum": 0,
            "description": "Caller ceiling; USD 1 = 100000000 microcents. Not a service price."
          },
          "context_refs": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "Preconfigured authorized connection references. Source endpoints and credentials belong to the registration, not this payload."
          },
          "correlation_id": {
            "type": "string",
            "description": "Opaque caller work ID. Included in the immutable purchase digest; does not establish identity or authority."
          },
          "auto_accept": {
            "type": "boolean",
            "default": false
          }
        },
        "required": [
          "service_key",
          "input_payload",
          "idempotency_key"
        ]
      },
      "Review": {
        "type": "object",
        "properties": {
          "verdict": {
            "type": "string",
            "enum": [
              "accepted",
              "rejected",
              "inconclusive"
            ]
          },
          "rationale": {
            "type": "string",
            "minLength": 1
          }
        },
        "required": [
          "verdict",
          "rationale"
        ]
      }
    }
  }
}