Organizations API

The Organizations API allows you to manage your Xata organizations, including listing, creating, updating, and deleting organizations. 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 organization information and list available regions

List organizations

Retrieves a list of all organizations you have access to.

GET /organizations

Summary

Returns a list of all organizations that the authenticated user has access to, including basic metadata such as ID, name, and creation/update timestamps.

Response

Status: 200 OK

{
  "organizations": [
    {
      "id": "org_123",
      "name": "My Organization",
      "createdAt": "2024-01-01T00:00:00Z",
      "updatedAt": "2024-01-01T00:00:00Z"
    }
  ]
}

Response schema

Get organization

Retrieves detailed information about a specific organization.

GET /organizations/{organizationID}

Summary

Returns comprehensive information about a specific organization by its ID, including all metadata and settings.

Path parameters

Response

Status: 200 OK

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

Response schema

Update organization

Updates the name of an organization.

PATCH /organizations/{organizationID}

Summary

Updates the organization's name. This is the only field that can be modified for an existing organization.

Path parameters

Request body

{
  "name": "New Organization Name"
}

Request body parameters

Response

Status: 200 OK

{
  "id": "org_123",
  "name": "New Organization Name",
  "createdAt": "2024-01-01T00:00:00Z",
  "updatedAt": "2024-01-01T00:00:00Z"
}

Response schema

Delete organization

Permanently deletes an organization and all its associated data. This action cannot be undone.

DELETE /organizations/{organizationID}

Summary

Permanently removes an organization and all associated projects, branches, and data. This is a destructive operation that cannot be reversed.

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 projects can be deployed within an organization.

GET /organizations/{organizationID}/regions

Summary

Returns a list of available geographic regions where new projects and branches can be deployed, 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

Organization

Basic organization information.

OrganizationID

Unique identifier for an organization.

Region

Information about an available deployment region.

OrganizationUpdateRequest

Request body for updating organization details.