Generated HTTP reference for the 6 operations the published OpenAPI document describes under policies.

Policies

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/policies`

GEThttps://api.codespar.dev/v1/policies

List policy rules for the authenticated org, sorted by order ASC.

Responses

Status	Body	Description
`200`	array of Policy	OK

Example request

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

const res = await fetch("https://api.codespar.dev/v1/policies", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`,
  },
});

const data = await res.json();

Example response 200

application/json

[
  {
    "id": "pol_0000000000000000",
    "name": "Example",
    "type": "allow",
    "config": {},
    "agents": [
      "string"
    ],
    "tools": [
      "string"
    ],
    "enabled": true,
    "order": 1,
    "createdAt": "2026-01-15T12:00:00.000Z",
    "updatedAt": "2026-01-15T12:00:00.000Z"
  }
]

POST `/v1/policies`

POSThttps://api.codespar.dev/v1/policies

Create a new policy rule.

Request body — PolicyCreate

Field	Type	Required	Description
`agents`	array of `string`	no	—
`config`	—	no	—
`enabled`	`boolean`	no	—
`name`	`string`	yes	—
`tools`	array of `string`	no	—
`type`	`"allow"` \| `"deny"` \| `"budget"` \| `"rate-limit"` \| `"time-window"` \| `"approval-required"`	yes	—

Responses

Status	Body	Description
`201`	Policy	OK

Response 201

Field	Type	Required	Description
`agents`	array of `string`	yes	—
`config`	object	yes	—
`createdAt`	`string (date-time)`	yes	—
`enabled`	`boolean`	yes	—
`id`	`string`	yes	—
`name`	`string`	yes	—
`order`	`number`	yes	—
`tools`	array of `string`	yes	—
`type`	`"allow"` \| `"deny"` \| `"budget"` \| `"rate-limit"` \| `"time-window"` \| `"approval-required"`	yes	—
`updatedAt`	`string (date-time)`	yes	—

Example request

curl -X POST https://api.codespar.dev/v1/policies \
  -H "Authorization: Bearer $CODESPAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "name": "Example",
       "type": "allow",
       "agents": [],
       "tools": [],
       "enabled": true
     }'

const res = await fetch("https://api.codespar.dev/v1/policies", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "name": "Example",
    "type": "allow",
    "agents": [],
    "tools": [],
    "enabled": true
  }),
});

const data = await res.json();

Example response 201

application/json

{
  "id": "pol_0000000000000000",
  "name": "Example",
  "type": "allow",
  "config": {},
  "agents": [
    "string"
  ],
  "tools": [
    "string"
  ],
  "enabled": true,
  "order": 1,
  "createdAt": "2026-01-15T12:00:00.000Z",
  "updatedAt": "2026-01-15T12:00:00.000Z"
}

POST `/v1/policies/reorder`

POSThttps://api.codespar.dev/v1/policies/reorder

Reorder policy rules. Atomic: if any id does not belong to the org, the entire operation rolls back and returns 404.

Request body — PolicyReorder

Field	Type	Required	Description
`ids`	array of `string`	yes	—

Responses

Status	Body	Description
`204`	—	No Content
`404`	object	Not Found

Example request

curl -X POST https://api.codespar.dev/v1/policies/reorder \
  -H "Authorization: Bearer $CODESPAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "ids": [
         "string"
       ]
     }'

const res = await fetch("https://api.codespar.dev/v1/policies/reorder", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "ids": [
      "string"
    ]
  }),
});

const data = await res.json();

GET `/v1/policies/{id}`

GEThttps://api.codespar.dev/v1/policies/{id}

Read one policy rule

Responses

Status	Body	Description
`200`	Policy	OK
`404`	object	Not Found

Response 200

Field	Type	Required	Description
`agents`	array of `string`	yes	—
`config`	object	yes	—
`createdAt`	`string (date-time)`	yes	—
`enabled`	`boolean`	yes	—
`id`	`string`	yes	—
`name`	`string`	yes	—
`order`	`number`	yes	—
`tools`	array of `string`	yes	—
`type`	`"allow"` \| `"deny"` \| `"budget"` \| `"rate-limit"` \| `"time-window"` \| `"approval-required"`	yes	—
`updatedAt`	`string (date-time)`	yes	—

Example request

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

const res = await fetch("https://api.codespar.dev/v1/policies/{id}", {
  method: "GET",
  headers: {
    Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`,
  },
});

const data = await res.json();

Example response 200

application/json

{
  "id": "pol_0000000000000000",
  "name": "Example",
  "type": "allow",
  "config": {},
  "agents": [
    "string"
  ],
  "tools": [
    "string"
  ],
  "enabled": true,
  "order": 1,
  "createdAt": "2026-01-15T12:00:00.000Z",
  "updatedAt": "2026-01-15T12:00:00.000Z"
}

PATCH `/v1/policies/{id}`

PATCHhttps://api.codespar.dev/v1/policies/{id}

Update a policy rule. Cross-org ids return 404. Invalidates the per-org cache on success.

Path parameters

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

Request body — PolicyUpdate

Field	Type	Required	Description
`agents`	array of `string`	no	—
`config`	—	no	—
`enabled`	`boolean`	no	—
`name`	`string`	no	—
`tools`	array of `string`	no	—
`type`	`"allow"` \| `"deny"` \| `"budget"` \| `"rate-limit"` \| `"time-window"` \| `"approval-required"`	no	—

Responses

Status	Body	Description
`200`	Policy	OK
`404`	object	Not Found

Response 200

Field	Type	Required	Description
`agents`	array of `string`	yes	—
`config`	object	yes	—
`createdAt`	`string (date-time)`	yes	—
`enabled`	`boolean`	yes	—
`id`	`string`	yes	—
`name`	`string`	yes	—
`order`	`number`	yes	—
`tools`	array of `string`	yes	—
`type`	`"allow"` \| `"deny"` \| `"budget"` \| `"rate-limit"` \| `"time-window"` \| `"approval-required"`	yes	—
`updatedAt`	`string (date-time)`	yes	—

Example request

curl -X PATCH https://api.codespar.dev/v1/policies/{id} \
  -H "Authorization: Bearer $CODESPAR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
       "name": "Example",
       "type": "allow",
       "agents": [
         "string"
       ],
       "tools": [
         "string"
       ],
       "enabled": true
     }'

const res = await fetch("https://api.codespar.dev/v1/policies/{id}", {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    "name": "Example",
    "type": "allow",
    "agents": [
      "string"
    ],
    "tools": [
      "string"
    ],
    "enabled": true
  }),
});

const data = await res.json();

Example response 200

application/json

{
  "id": "pol_0000000000000000",
  "name": "Example",
  "type": "allow",
  "config": {},
  "agents": [
    "string"
  ],
  "tools": [
    "string"
  ],
  "enabled": true,
  "order": 1,
  "createdAt": "2026-01-15T12:00:00.000Z",
  "updatedAt": "2026-01-15T12:00:00.000Z"
}

DELETE `/v1/policies/{id}`

DELETEhttps://api.codespar.dev/v1/policies/{id}

Delete a policy rule. Cross-org ids return 404. Invalidates the per-org cache on success.

Path parameters

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

Responses

Status	Body	Description
`204`	—	No Content
`404`	object	Not Found

Example request

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

const res = await fetch("https://api.codespar.dev/v1/policies/{id}", {
  method: "DELETE",
  headers: {
    Authorization: `Bearer ${process.env.CODESPAR_API_KEY}`,
  },
});

const data = await res.json();

Policies

Policies

GET /v1/policies

POST /v1/policies

POST /v1/policies/reorder

GET /v1/policies/{id}

PATCH /v1/policies/{id}

DELETE /v1/policies/{id}

On this page

GET `/v1/policies`

POST `/v1/policies`

POST `/v1/policies/reorder`

GET `/v1/policies/{id}`

PATCH `/v1/policies/{id}`

DELETE `/v1/policies/{id}`