Generated HTTP reference for the 5 operations the published OpenAPI document describes under mandates.

Mandates

This page is generated from the published OpenAPI document. It is complete with respect to that document and says nothing about surfaces the document does not describe yet. See what is generated here for what that means.

Base URL: https://api.codespar.dev

Every operation below requires a Bearer token. See Authentication.

GET `/v1/mandates`

List consumer allowances

Query parameters

Name	Type	Required	Description
`consumer_id`	`string`	no	—
`limit`	`integer`	no	—
`status`	`"active"` \| `"paused"` \| `"revoked"` \| `"expired"`	no	—

Responses

Status	Body	Description
`200`	object	OK
`400`	object	The query did not match the schema: an unknown `status`, a `limit` outside 1..200, or a `limit` that is not a number. `details.issues` carries the Zod issues.

Response 200

Field	Type	Required	Description
`mandates`	array of object	yes	—

Example response

{
  "mandates": [
    {
      "id": "obj_0000000000000000",
      "consumer_id": "csm_0000000000000000",
      "agent_id": "agt_0000000000000000",
      "purpose": "string",
      "merchant_allowlist": [
        "string"
      ],
      "merchant_pin_kind": "pix-key",
      "cap_minor": "1000",
      "per_tx_cap_minor": "1000",
      "currency": "BRL",
      "status": "active",
      "expires_at": "2026-01-15T12:00:00.000Z",
      "created_at": "2026-01-15T12:00:00.000Z"
    }
  ]
}

Example request

curl -X GET https://api.codespar.dev/v1/mandates \
  -H "Authorization: Bearer $CODESPAR_API_KEY"

GET `/v1/mandates/{id}`

Read one consumer allowance

Path parameters

Name	Type	Required	Description
`id`	`string`	yes	—

Responses

Status	Body	Description
`200`	object	OK
`404`	object	No such allowance for this credential's organization. An allowance belonging to another organization answers exactly the same way: the org predicate sits in the SELECT, so the handler cannot tell absent from someone else's, and must not.

Response 200

Field	Type	Required	Description
`agent_id`	`string`	yes	The agent this allowance authorizes to spend.
`cap_minor`	`string`	yes	Total spend authorized over the life of the allowance, in minor units. A STRING: the column is `bigint` and the driver hands it back as text, so parse it as an integer and never as a float.
`consumer_id`	`string`	yes	—
`created_at`	`string (date-time)`	yes	—
`currency`	`string`	yes	Left open here rather than closed. The column admits BRL, USD, MXN, COP, ARS, USDC and BRLA today, and that list is a CHECK constraint on our side rather than a promise on the wire.
`display_name`	`string,null`	yes	—
`expires_at`	`string (date-time)`	yes	Never null: the column is NOT NULL.
`id`	`string`	yes	—
`intent_note`	`string,null`	yes	—
`merchant_allowlist`	array of `string`	yes	The payees this allowance may pay, read as `merchant_pin_kind` says to read them. Never empty: `consumer_mandates_allowlist_nonempty` refuses a row whose allowlist is not an array of at least one entry, so an allowance that authorizes nothing cannot exist.
`merchant_pin_kind`	`"pix-key"` \| `"merchant-id"` \| `"mcc"`	yes	How each allowlist entry pins a payee. The v1 rail pins by Pix key.
`per_tx_cap_minor`	`string`	yes	Per-transaction ceiling, in minor units. Same string shape as `cap_minor`.
`purpose`	`string`	yes	—
`status`	`"active"` \| `"paused"` \| `"revoked"` \| `"expired"`	yes	—

Example response

{
  "id": "obj_0000000000000000",
  "consumer_id": "csm_0000000000000000",
  "agent_id": "agt_0000000000000000",
  "purpose": "string",
  "merchant_allowlist": [
    "string"
  ],
  "merchant_pin_kind": "pix-key",
  "cap_minor": "1000",
  "per_tx_cap_minor": "1000",
  "currency": "BRL",
  "status": "active",
  "expires_at": "2026-01-15T12:00:00.000Z",
  "created_at": "2026-01-15T12:00:00.000Z"
}

Example request

curl -X GET https://api.codespar.dev/v1/mandates/{id} \
  -H "Authorization: Bearer $CODESPAR_API_KEY"

POST `/v1/mandates/{id}/pause`

Pause an allowance

Path parameters

Name	Type	Required	Description
`id`	`string`	yes	—

Request body

Field	Type	Required	Description
`reason`	`string`	no	Recorded in the evidence row's metadata, alongside the from/to pair. Not echoed in the response.

Responses

Status	Body	Description
`200`	object	OK
`400`	object	A body was sent and did not match the schema. `details.issues` carries the Zod issues.
`404`	object	No such allowance for this credential's organization. An allowance belonging to another organization answers exactly the same way: the org predicate sits in the SELECT, so the handler cannot tell absent from someone else's, and must not.
`409`	object	`invalid_transition` when the allowance's current status is not a legal source for this verb. `transition_conflict` when another request moved the allowance between this one's read and its write: the UPDATE is guarded on the status that was read, so a concurrent transition loses rather than double-applying, and the evidence row is written in the same transaction as the status change or not at all.

Response 200

Field	Type	Required	Description
`changed`	`boolean`	yes	False when the allowance was already in this state. Nothing was written and no evidence row was appended.
`mandate`	object	yes	—

Example response

{
  "mandate": {
    "id": "obj_0000000000000000",
    "status": "paused"
  },
  "changed": true
}

Example request

curl -X POST https://api.codespar.dev/v1/mandates/{id}/pause \
  -H "Authorization: Bearer $CODESPAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "reason": "string"
     }'

POST `/v1/mandates/{id}/resume`

Resume a paused allowance

Path parameters

Name	Type	Required	Description
`id`	`string`	yes	—

Request body

Field	Type	Required	Description
`reason`	`string`	no	Recorded in the evidence row's metadata, alongside the from/to pair. Not echoed in the response.

Responses

Status	Body	Description
`200`	object	OK
`400`	object	A body was sent and did not match the schema. `details.issues` carries the Zod issues.
`404`	object	No such allowance for this credential's organization. An allowance belonging to another organization answers exactly the same way: the org predicate sits in the SELECT, so the handler cannot tell absent from someone else's, and must not.
`409`	object	`invalid_transition` when the allowance's current status is not a legal source for this verb. `transition_conflict` when another request moved the allowance between this one's read and its write: the UPDATE is guarded on the status that was read, so a concurrent transition loses rather than double-applying, and the evidence row is written in the same transaction as the status change or not at all.

Response 200

Field	Type	Required	Description
`changed`	`boolean`	yes	False when the allowance was already in this state. Nothing was written and no evidence row was appended.
`mandate`	object	yes	—

Example response

{
  "mandate": {
    "id": "obj_0000000000000000",
    "status": "active"
  },
  "changed": true
}

Example request

curl -X POST https://api.codespar.dev/v1/mandates/{id}/resume \
  -H "Authorization: Bearer $CODESPAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "reason": "string"
     }'

POST `/v1/mandates/{id}/revoke`

Revoke an allowance

Path parameters

Name	Type	Required	Description
`id`	`string`	yes	—

Request body

Field	Type	Required	Description
`reason`	`string`	no	Recorded in the evidence row's metadata, alongside the from/to pair. Not echoed in the response.

Responses

Status	Body	Description
`200`	object	OK
`400`	object	A body was sent and did not match the schema. `details.issues` carries the Zod issues.
`404`	object	No such allowance for this credential's organization. An allowance belonging to another organization answers exactly the same way: the org predicate sits in the SELECT, so the handler cannot tell absent from someone else's, and must not.
`409`	object	`invalid_transition` when the allowance's current status is not a legal source for this verb. `transition_conflict` when another request moved the allowance between this one's read and its write: the UPDATE is guarded on the status that was read, so a concurrent transition loses rather than double-applying, and the evidence row is written in the same transaction as the status change or not at all.

Response 200

Field	Type	Required	Description
`changed`	`boolean`	yes	False when the allowance was already in this state. Nothing was written and no evidence row was appended.
`mandate`	object	yes	—

Example response

{
  "mandate": {
    "id": "obj_0000000000000000",
    "status": "revoked"
  },
  "changed": true
}

Example request

curl -X POST https://api.codespar.dev/v1/mandates/{id}/revoke \
  -H "Authorization: Bearer $CODESPAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "reason": "string"
     }'

Mandates

Mandates

GET /v1/mandates

GET /v1/mandates/{id}

POST /v1/mandates/{id}/pause

POST /v1/mandates/{id}/resume

POST /v1/mandates/{id}/revoke

On this page

GET `/v1/mandates`

GET `/v1/mandates/{id}`

POST `/v1/mandates/{id}/pause`

POST `/v1/mandates/{id}/resume`

POST `/v1/mandates/{id}/revoke`