Projects API

The Projects API allows you to manage your Xata projects, including listing, creating, updating, and deleting projects. All endpoints require authentication via API key or OIDC.

Authentication

All endpoints require authentication. You can authenticate using:

• API Key: Include your API key in the Authorization header: Authorization: Bearer <your-api-key>
• OIDC: Use OIDC tokens for authentication

Required scopes for different operations:

• project:read: Read project information and list projects
• project:write: Create, update, and delete projects

List projects

Retrieves a list of all projects within an organization.

GET /organizations/{organizationID}/projects

Summary

Returns a paginated list of projects in an organization with basic metadata including ID, name, creation date, and update timestamp.

Path parameters

Response

Status: 200 OK

{
  "projects": [
    {
      "id": "proj_123",
      "name": "My Project",
      "createdAt": "2024-01-01T00:00:00Z",
      "updatedAt": "2024-01-01T00:00:00Z"
    }
  ]
}

Response schema

Create project

Creates a new project within an organization.

POST /organizations/{organizationID}/projects

Summary

Creates a new project with the specified name. The project will be created in the organization's default region.

Path parameters

Request body

{
  "name": "New Project"
}

Request body parameters

Response

Status: 201 Created

{
  "id": "proj_123",
  "name": "New Project",
  "createdAt": "2024-01-01T00:00:00Z",
  "updatedAt": "2024-01-01T00:00:00Z"
}

Response schema

Get project

Retrieves detailed information about a specific project.

GET /organizations/{organizationID}/projects/{projectID}

Summary

Returns comprehensive information about a project including all metadata and settings.

Path parameters

Response

Status: 200 OK

{
  "id": "proj_123",
  "name": "My Project",
  "createdAt": "2024-01-01T00:00:00Z",
  "updatedAt": "2024-01-01T00:00:00Z"
}

Response schema

Update project

Updates the configuration of a project.

PATCH /organizations/{organizationID}/projects/{projectID}

Summary

Updates project metadata such as name. Note that most project configuration changes require creating a new project.

Path parameters

Request body

{
  "name": "Updated Project Name"
}

Request body parameters

Response

Status: 200 OK

{
  "id": "proj_123",
  "name": "Updated Project Name",
  "createdAt": "2024-01-01T00:00:00Z",
  "updatedAt": "2024-01-01T00:00:00Z"
}

Response schema

Delete project

Permanently deletes a project and all its associated data.

DELETE /organizations/{organizationID}/projects/{projectID}

Summary

Permanently removes a project and all associated branches and data. This action cannot be undone and will terminate all active connections.

Path parameters

Response

Status: 204 No Content

No response body is returned on successful deletion.

Get available regions

Retrieves a list of all regions where new branches can be deployed within a project.

GET /organizations/{organizationID}/projects/{projectID}/regions

Summary

Returns a list of available geographic regions where new branches can be deployed within the specified project, along with information about public access capabilities for each region.

Path parameters

Response

Status: 200 OK

{
  "regions": [
    {
      "id": "us-east-1",
      "publicAccess": false
    },
    {
      "id": "eu-west-1",
      "publicAccess": true
    }
  ]
}

Response schema

Error Handling

The API uses standard HTTP status codes and returns error responses in the following format:

{
  "id": "error_identifier",
  "message": "Human-readable error message explaining the issue"
}

Common error responses

Schema Reference

Core Data Models

Project

Basic project information.

ProjectCreationRequest

Request body for creating a new project.

ProjectUpdateRequest

Request body for updating project details.

Region

Information about an available deployment region.