Definitions
8 operations.
| Method | Endpoint | Description |
|---|---|---|
| GET | /api/v1/projects/{projectId}/definitions | List project definitions |
| POST | /api/v1/projects/{projectId}/definitions | Create a definition |
| GET | /api/v1/projects/{projectId}/definitions/{definitionId} | Get a definition |
| PATCH | /api/v1/projects/{projectId}/definitions/{definitionId} | Update project definition |
| DELETE | /api/v1/projects/{projectId}/definitions/{definitionId} | Delete project definition |
| GET | /api/v1/projects/{projectId}/definitions/{definitionId}/revisions | List immutable Definition revisions |
| POST | /api/v1/projects/{projectId}/definitions/{definitionId}/revisions | Create an immutable Definition revision |
| GET | /api/v1/projects/{projectId}/definitions/{definitionId}/revisions/{definitionRevisionId} | Get an immutable Definition revision |
List project definitions
GET /api/v1/projects/{projectId}/definitions
Parameters
path
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | required | Identifies the Project that owns the addressed resource. Applies to List project definitions. |
query
| Name | Type | Required | Description |
|---|---|---|---|
kind | "domain" | "integration" | "operation" | "presentation" | optional | Filters definitions to the requested definition kind. Applies to List project definitions. |
limit | integer | optional | Sets the maximum number of resources returned in this page. Applies to List project definitions. |
cursor | string | optional | Opaque cursor returned by the previous page; omit it to read the first page. Applies to List project definitions. |
includeSource | boolean | optional | Requests source text alongside matching definition elements. Applies to List project definitions. |
Responses
| Status | Description | Body |
|---|---|---|
200 | Response for status 200 | application/json — object — definitions: array<object> (required); pagination: object (required) |
400 | The request is malformed or cannot be processed. | application/json — PublicApiError — error: object (required) |
401 | Authentication failed. The Authorization header is missing, or the credential is invalid or expired. | application/json — PublicApiError — error: object (required) |
403 | Access denied. The authenticated user does not have permission to perform this action. | application/json — PublicApiError — error: object (required) |
404 | Resource not found. | application/json — PublicApiError — error: object (required) |
409 | Request conflicts with current state of the resource, including safe deployment conflict classifications. | application/json — PublicApiError — error: object (required) |
422 | Request validation failed. Check the request body, query parameters, or path parameters. | application/json — PublicApiError — error: object (required) |
429 | Too many requests. The code foreign_resource_rate_limited means the caller made too many requests for Projects outside its reach: correct the Project id instead of retrying. | application/json — PublicApiError — error: object (required) |
500 | The server could not complete the request. | application/json — PublicApiError — error: object (required) |
503 | Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff. | application/json — PublicApiError — error: object (required) |
Create a definition
POST /api/v1/projects/{projectId}/definitions
Create a definition with its initial immutable revision.
Parameters
path
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | required | Identifies the Project that owns the addressed resource. Applies to Create a definition. |
Request body
Required — Request body for: Create a definition.
application/json
| Name | Type | Required | Description |
|---|---|---|---|
kind | "domain" | "integration" | "operation" | "presentation" | required | |
slug | string | required | |
name | string | required | |
source | object | required | |
attachments | array<object> | optional |
Responses
| Status | Description | Body |
|---|---|---|
201 | Response for status 201 | application/json — object — id: string (required); projectId: string (required); kind: "domain" | "integration" | "operation" | "presentation" (required); slug: string (required); name: string (required); status: "active" | "deleting" (required); latestRevision: object | null (required) |
400 | The request is malformed or cannot be processed. | application/json — PublicApiError — error: object (required) |
401 | Authentication failed. The Authorization header is missing, or the credential is invalid or expired. | application/json — PublicApiError — error: object (required) |
403 | Access denied. The authenticated user does not have permission to perform this action. | application/json — PublicApiError — error: object (required) |
404 | Resource not found. | application/json — PublicApiError — error: object (required) |
409 | Request conflicts with current state of the resource, including safe deployment conflict classifications. | application/json — PublicApiError — error: object (required) |
422 | Request validation failed. Check the request body, query parameters, or path parameters. | application/json — PublicApiError — error: object (required) |
429 | Too many requests. The code foreign_resource_rate_limited means the caller made too many requests for Projects outside its reach: correct the Project id instead of retrying. | application/json — PublicApiError — error: object (required) |
500 | The server could not complete the request. | application/json — PublicApiError — error: object (required) |
503 | Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff. | application/json — PublicApiError — error: object (required) |
Get a definition
GET /api/v1/projects/{projectId}/definitions/{definitionId}
Retrieve one definition element by its identifier.
Parameters
path
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | required | Identifies the Project that owns the addressed resource. Applies to Get a definition. |
definitionId | string | required | Identifies the definition element being addressed. Applies to Get a definition. |
Responses
| Status | Description | Body |
|---|---|---|
200 | Response for status 200 | application/json — object — id: string (required); projectId: string (required); kind: "domain" | "integration" | "operation" | "presentation" (required); slug: string (required); name: string (required); status: "active" | "deleting" (required); latestRevision: object | null (required) |
400 | The request is malformed or cannot be processed. | application/json — PublicApiError — error: object (required) |
401 | Authentication failed. The Authorization header is missing, or the credential is invalid or expired. | application/json — PublicApiError — error: object (required) |
403 | Access denied. The authenticated user does not have permission to perform this action. | application/json — PublicApiError — error: object (required) |
404 | Resource not found. | application/json — PublicApiError — error: object (required) |
409 | Request conflicts with current state of the resource, including safe deployment conflict classifications. | application/json — PublicApiError — error: object (required) |
422 | Request validation failed. Check the request body, query parameters, or path parameters. | application/json — PublicApiError — error: object (required) |
429 | Too many requests. The code foreign_resource_rate_limited means the caller made too many requests for Projects outside its reach: correct the Project id instead of retrying. | application/json — PublicApiError — error: object (required) |
500 | The server could not complete the request. | application/json — PublicApiError — error: object (required) |
503 | Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff. | application/json — PublicApiError — error: object (required) |
Update project definition
PATCH /api/v1/projects/{projectId}/definitions/{definitionId}
Parameters
path
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | required | Identifies the Project that owns the addressed resource. Applies to Update project definition. |
definitionId | string | required | Identifies the definition element being addressed. Applies to Update project definition. |
Request body
Required — Request body for: Update project definition.
application/json
| Name | Type | Required | Description |
|---|---|---|---|
name | string | optional | |
source | object | optional | |
attachments | array<object> | optional |
Responses
| Status | Description | Body |
|---|---|---|
200 | Response for status 200 | application/json — object — id: string (required); projectId: string (required); kind: "domain" | "integration" | "operation" | "presentation" (required); slug: string (required); name: string (required); status: "active" | "deleting" (required); latestRevision: object | null (required) |
400 | The request is malformed or cannot be processed. | application/json — PublicApiError — error: object (required) |
401 | Authentication failed. The Authorization header is missing, or the credential is invalid or expired. | application/json — PublicApiError — error: object (required) |
403 | Access denied. The authenticated user does not have permission to perform this action. | application/json — PublicApiError — error: object (required) |
404 | Resource not found. | application/json — PublicApiError — error: object (required) |
409 | Request conflicts with current state of the resource, including safe deployment conflict classifications. | application/json — PublicApiError — error: object (required) |
422 | Request validation failed. Check the request body, query parameters, or path parameters. | application/json — PublicApiError — error: object (required) |
429 | Too many requests. The code foreign_resource_rate_limited means the caller made too many requests for Projects outside its reach: correct the Project id instead of retrying. | application/json — PublicApiError — error: object (required) |
500 | The server could not complete the request. | application/json — PublicApiError — error: object (required) |
503 | Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff. | application/json — PublicApiError — error: object (required) |
Delete project definition
DELETE /api/v1/projects/{projectId}/definitions/{definitionId}
Parameters
path
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | required | Identifies the Project that owns the addressed resource. Applies to Delete project definition. |
definitionId | string | required | Identifies the definition element being addressed. Applies to Delete project definition. |
Responses
| Status | Description | Body |
|---|---|---|
202 | Response for status 202 | application/json — object — id: string (required); projectId: string (required); kind: "domain" | "integration" | "operation" | "presentation" (required); slug: string (required); name: string (required); status: "active" | "deleting" (required); latestRevision: object | null (required) |
400 | The request is malformed or cannot be processed. | application/json — PublicApiError — error: object (required) |
401 | Authentication failed. The Authorization header is missing, or the credential is invalid or expired. | application/json — PublicApiError — error: object (required) |
403 | Access denied. The authenticated user does not have permission to perform this action. | application/json — PublicApiError — error: object (required) |
404 | Resource not found. | application/json — PublicApiError — error: object (required) |
409 | Request conflicts with current state of the resource, including safe deployment conflict classifications. | application/json — PublicApiError — error: object (required) |
422 | Request validation failed. Check the request body, query parameters, or path parameters. | application/json — PublicApiError — error: object (required) |
429 | Too many requests. The code foreign_resource_rate_limited means the caller made too many requests for Projects outside its reach: correct the Project id instead of retrying. | application/json — PublicApiError — error: object (required) |
500 | The server could not complete the request. | application/json — PublicApiError — error: object (required) |
503 | Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff. | application/json — PublicApiError — error: object (required) |
List immutable Definition revisions
GET /api/v1/projects/{projectId}/definitions/{definitionId}/revisions
Lists immutable revisions for the specified Definition in the resolved Project. Results are cursor-paginated; use pagination.nextCursor unchanged for the next page. Project, Definition, and cursor scope are checked together, so foreign resources return 404.
Parameters
path
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | required | Identifies the Project that owns the addressed resource. Applies to List immutable Definition revisions. |
definitionId | string | required | Identifies the definition element being addressed. Applies to List immutable Definition revisions. |
query
| Name | Type | Required | Description |
|---|---|---|---|
limit | integer | optional | Sets the maximum number of resources returned in this page. Applies to List immutable Definition revisions. |
cursor | string | optional | Opaque cursor returned by the previous page; omit it to read the first page. Applies to List immutable Definition revisions. |
Responses
| Status | Description | Body |
|---|---|---|
200 | Response for status 200 | application/json — object — revisions: array<object> (required); pagination: object (required) |
400 | The request is malformed or cannot be processed. | application/json — PublicApiError — error: object (required) |
401 | Authentication failed. The Authorization header is missing, or the credential is invalid or expired. | application/json — PublicApiError — error: object (required) |
403 | Access denied. The authenticated user does not have permission to perform this action. | application/json — PublicApiError — error: object (required) |
404 | Resource not found. | application/json — PublicApiError — error: object (required) |
409 | Request conflicts with current state of the resource, including safe deployment conflict classifications. | application/json — PublicApiError — error: object (required) |
422 | Request validation failed. Check the request body, query parameters, or path parameters. | application/json — PublicApiError — error: object (required) |
429 | Too many requests. The code foreign_resource_rate_limited means the caller made too many requests for Projects outside its reach: correct the Project id instead of retrying. | application/json — PublicApiError — error: object (required) |
500 | The server could not complete the request. | application/json — PublicApiError — error: object (required) |
503 | Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff. | application/json — PublicApiError — error: object (required) |
Create an immutable Definition revision
POST /api/v1/projects/{projectId}/definitions/{definitionId}/revisions
Validates and stores a new immutable Definition revision under the resolved Project and Definition. The source and attachment graph are captured at creation; a prior revision is never edited or implicitly released. Invalid source or attachment data returns 422, and an unknown or foreign target returns 404.
Parameters
path
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | required | Identifies the Project that owns the addressed resource. Applies to Create an immutable Definition revision. |
definitionId | string | required | Identifies the definition element being addressed. Applies to Create an immutable Definition revision. |
Request body
Required — Request body for: Create an immutable Definition revision.
application/json
| Name | Type | Required | Description |
|---|---|---|---|
source | object | required | |
attachments | array<object> | optional |
Responses
| Status | Description | Body |
|---|---|---|
201 | Response for status 201 | application/json — object — id: string (required); definitionId: string (required); number: integer (required); source: object (required); createdByUserId: string (required); attachments: array<object> (required) |
400 | The request is malformed or cannot be processed. | application/json — PublicApiError — error: object (required) |
401 | Authentication failed. The Authorization header is missing, or the credential is invalid or expired. | application/json — PublicApiError — error: object (required) |
403 | Access denied. The authenticated user does not have permission to perform this action. | application/json — PublicApiError — error: object (required) |
404 | Resource not found. | application/json — PublicApiError — error: object (required) |
409 | Request conflicts with current state of the resource, including safe deployment conflict classifications. | application/json — PublicApiError — error: object (required) |
422 | Request validation failed. Check the request body, query parameters, or path parameters. | application/json — PublicApiError — error: object (required) |
429 | Too many requests. The code foreign_resource_rate_limited means the caller made too many requests for Projects outside its reach: correct the Project id instead of retrying. | application/json — PublicApiError — error: object (required) |
500 | The server could not complete the request. | application/json — PublicApiError — error: object (required) |
503 | Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff. | application/json — PublicApiError — error: object (required) |
Get an immutable Definition revision
GET /api/v1/projects/{projectId}/definitions/{definitionId}/revisions/{definitionRevisionId}
Returns the exact immutable Definition revision selected by the Project, Definition, and revision coordinates. The response contains the persisted source and attachment metadata; foreign or absent revisions return 404.
Parameters
path
| Name | Type | Required | Description |
|---|---|---|---|
projectId | string | required | Identifies the Project that owns the addressed resource. Applies to Get an immutable Definition revision. |
definitionId | string | required | Identifies the definition element being addressed. Applies to Get an immutable Definition revision. |
definitionRevisionId | string | required | Identifies the immutable Definition revision being addressed. Applies to Get an immutable Definition revision. |
Responses
| Status | Description | Body |
|---|---|---|
200 | Response for status 200 | application/json — object — id: string (required); definitionId: string (required); number: integer (required); source: object (required); createdByUserId: string (required); attachments: array<object> (required) |
400 | The request is malformed or cannot be processed. | application/json — PublicApiError — error: object (required) |
401 | Authentication failed. The Authorization header is missing, or the credential is invalid or expired. | application/json — PublicApiError — error: object (required) |
403 | Access denied. The authenticated user does not have permission to perform this action. | application/json — PublicApiError — error: object (required) |
404 | Resource not found. | application/json — PublicApiError — error: object (required) |
409 | Request conflicts with current state of the resource, including safe deployment conflict classifications. | application/json — PublicApiError — error: object (required) |
422 | Request validation failed. Check the request body, query parameters, or path parameters. | application/json — PublicApiError — error: object (required) |
429 | Too many requests. The code foreign_resource_rate_limited means the caller made too many requests for Projects outside its reach: correct the Project id instead of retrying. | application/json — PublicApiError — error: object (required) |
500 | The server could not complete the request. | application/json — PublicApiError — error: object (required) |
503 | Service temporarily unavailable (e.g. execution capacity exhausted). The response carries a Retry-After header; retry with backoff. | application/json — PublicApiError — error: object (required) |