Veto/docs

Projects API

CRUD endpoints for projects — the scope for API keys, decisions, and tool registrations within an organization.

Projects group tools, decisions, and API keys within an organization. Every API key is scoped to a project, and decisions are logged per-project. Creating a project automatically generates an API key for it.

Most endpoints accept both JWT and API key auth. Mutating operations (create, update, delete, regenerate key) require JWT user authentication.

GET /v1/projects

List projects for an organization.

Headers

HeaderRequiredDescription
X-Veto-API-Key or AuthorizationYesAPI key or Bearer JWT

Query parameters

ParameterTypeRequiredDescription
organizationIdstringYes (JWT auth)Organization to list projects for. API key auth auto-scopes to the key's org.

Response

{
  "data": [
    {
      "_id": "proj_abc123",
      "organizationId": "org_xyz789",
      "name": "Production",
      "isDefault": true,
      "createdAt": "2025-01-15T10:00:00Z",
      "updatedAt": "2025-01-20T14:30:00Z"
    },
    {
      "_id": "proj_def456",
      "organizationId": "org_xyz789",
      "name": "Staging",
      "isDefault": false,
      "createdAt": "2025-01-16T09:00:00Z",
      "updatedAt": null
    }
  ]
}

Errors

StatusCodeDescription
400missing_organizationorganizationId query parameter not provided
403authorization_errorNot a member of the organization

Example

curl "https://api.veto.so/v1/projects?organizationId=org_xyz789" \
  -H "Authorization: Bearer $JWT_TOKEN"

POST /v1/projects

Create a new project. Requires JWT auth. Automatically creates an API key for the project. If this is the first project in the organization, it becomes the default project.

Headers

HeaderRequiredDescription
AuthorizationYesBearer JWT
Content-TypeYesapplication/json

Body

{
  "organizationId": "org_xyz789",
  "name": "Production"
}
FieldTypeRequiredDescription
organizationIdstringYesOrganization to create the project in
namestringYesProject name (1-100 chars)

Response (201)

{
  "_id": "proj_abc123",
  "organizationId": "org_xyz789",
  "name": "Production",
  "isDefault": true,
  "createdAt": "2025-01-20T14:30:00Z",
  "updatedAt": null,
  "apiKey": "veto_abc123def456ghi789..."
}
FieldTypeDescription
_idstringProject ID
organizationIdstringParent organization ID
namestringProject name
isDefaultbooleanWhether this is the default project
createdAtstringISO 8601 creation timestamp
updatedAtstring?ISO 8601 last update timestamp
apiKeystringFull API key for the project (only shown once)

Errors

StatusCodeDescription
403authorization_errorAPI keys cannot create projects, or not a member of the org

Example

curl -X POST https://api.veto.so/v1/projects \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "organizationId": "org_xyz789",
    "name": "Staging"
  }'

GET /v1/projects/:id

Get a single project by ID.

Headers

HeaderRequiredDescription
X-Veto-API-Key or AuthorizationYesAPI key or Bearer JWT

Path parameters

ParameterTypeDescription
idstringProject ID

Response

{
  "_id": "proj_abc123",
  "organizationId": "org_xyz789",
  "name": "Production",
  "isDefault": true,
  "createdAt": "2025-01-15T10:00:00Z",
  "updatedAt": "2025-01-20T14:30:00Z"
}

Errors

StatusCodeDescription
403authorization_errorNot a member of the organization
404not_foundProject does not exist

Example

curl https://api.veto.so/v1/projects/proj_abc123 \
  -H "Authorization: Bearer $JWT_TOKEN"

PUT /v1/projects/:id

Update a project. Requires JWT auth.

Headers

HeaderRequiredDescription
AuthorizationYesBearer JWT
Content-TypeYesapplication/json

Path parameters

ParameterTypeDescription
idstringProject ID

Body

{
  "organizationId": "org_xyz789",
  "name": "Production v2"
}
FieldTypeRequiredDescription
organizationIdstringYesOrganization ID (for ownership verification)
namestringYesNew project name

Response

{
  "_id": "proj_abc123",
  "organizationId": "org_xyz789",
  "name": "Production v2",
  "isDefault": true,
  "createdAt": "2025-01-15T10:00:00Z",
  "updatedAt": "2025-01-21T09:00:00Z"
}

Errors

StatusCodeDescription
400missing_organizationorganizationId not provided in body
403authorization_errorAPI keys cannot update projects, or not a member of the org
404not_foundProject does not exist

Example

curl -X PUT https://api.veto.so/v1/projects/proj_abc123 \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "organizationId": "org_xyz789",
    "name": "Production v2"
  }'

DELETE /v1/projects/:id

Delete a project. Requires JWT auth.

Headers

HeaderRequiredDescription
AuthorizationYesBearer JWT

Path parameters

ParameterTypeDescription
idstringProject ID

Query parameters

ParameterTypeRequiredDescription
organizationIdstringYesOrganization ID (for ownership verification)

Response

{
  "success": true
}

Errors

StatusCodeDescription
400missing_organizationorganizationId query parameter not provided
403authorization_errorAPI keys cannot delete projects, or not a member of the org
404not_foundProject does not exist

Example

curl -X DELETE "https://api.veto.so/v1/projects/proj_abc123?organizationId=org_xyz789" \
  -H "Authorization: Bearer $JWT_TOKEN"

POST /v1/projects/:id/regenerate-key

Regenerate the API key for a project. Creates a new key and revokes all existing keys for the project. Requires JWT auth.

Headers

HeaderRequiredDescription
AuthorizationYesBearer JWT
Content-TypeYesapplication/json

Path parameters

ParameterTypeDescription
idstringProject ID

Body

{
  "organizationId": "org_xyz789"
}
FieldTypeRequiredDescription
organizationIdstringYesOrganization ID (for ownership verification)

Response

{
  "apiKey": "veto_newkey123def456..."
}

The old API keys for this project are immediately revoked. Any SDK clients using the old key will start receiving 401 errors.

Errors

StatusCodeDescription
400missing_organizationorganizationId not provided in body
403authorization_errorAPI keys cannot regenerate keys, or not a member of the org
404not_foundProject does not exist

Example

curl -X POST https://api.veto.so/v1/projects/proj_abc123/regenerate-key \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "organizationId": "org_xyz789" }'

Project response fields

FieldTypeDescription
_idstringProject ID
organizationIdstringParent organization ID
namestringProject name
isDefaultbooleanWhether this is the organization's default project
createdAtstringISO 8601 creation timestamp
updatedAtstring?ISO 8601 last update timestamp

Organizations API

CRUD endpoints for organizations — the top-level scope for projects, policies, and API keys.

Events API

Server-Sent Events (SSE) stream for real-time decision, approval, and policy change notifications.

On this page

GET /v1/projectsHeadersQuery parametersResponseErrorsExamplePOST /v1/projectsHeadersBodyResponse (201)ErrorsExampleGET /v1/projects/:idHeadersPath parametersResponseErrorsExamplePUT /v1/projects/:idHeadersPath parametersBodyResponseErrorsExampleDELETE /v1/projects/:idHeadersPath parametersQuery parametersResponseErrorsExamplePOST /v1/projects/:id/regenerate-keyHeadersPath parametersBodyResponseErrorsExampleProject response fields