Skip to content

Projects

Project management operations

Create a new project

POST /projects

Code samples

curl -X POST https://localhost:9243/api/v0.9/projects \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d @payload.json

Creates a new project within the organization specified in the JWT token. Organization ID is automatically extracted from the token and does not need to be provided.

Payload

{
  "id": "default-project",
  "displayName": "Default Project",
  "description": "This is the default project for development"
}

Authentication

Parameters

Name In Type Required Description
body body CreateProjectRequest true none

Example responses

201 Response

{
  "id": "default-project",
  "displayName": "Default Project",
  "description": "This is the default project for development",
  "organizationId": "acme",
  "createdBy": "john.doe",
  "updatedBy": "john.doe",
  "createdAt": "2023-10-12T10:30:00Z",
  "updatedAt": "2023-10-12T10:30:00Z"
}

400 Response

{
  "status": "error",
  "code": "VALIDATION_FAILED",
  "message": "The request failed validation.",
  "errors": [
    {
      "field": "<name of the offending field>",
      "message": "<reason this field failed validation>"
    }
  ]
}

401 Response

{
  "status": "error",
  "code": "UNAUTHORIZED",
  "message": "Authorization header is required, or the token is invalid or expired."
}

403 Response

{
  "status": "error",
  "code": "FORBIDDEN",
  "message": "You do not have permission to perform this action."
}

409 Response

{
  "status": "error",
  "code": "CONFLICT",
  "message": "The request conflicts with the current state of the resource."
}

500 Response

{
  "status": "error",
  "code": "INTERNAL_ERROR",
  "message": "An unexpected error occurred.",
  "trackingId": "4f1c6f2e-8a4b-4c93-b1de-9f2f6f0c2a11"
}

Responses

Status Meaning Description Schema
201 Created Project created successfully Project
400 Bad Request Bad Request. Invalid request or validation error. Error
401 Unauthorized Unauthorized. Authentication credentials are missing or invalid. Error
403 Forbidden Forbidden. The authenticated user does not have permission to access this resource. Error
409 Conflict Conflict. The request conflicts with the current state of the resource. Error
500 Internal Server Error Internal Server Error. Error

Response Headers

Status Header Type Format Description
201 Location string uri URL of the newly created resource.

Get all projects for current user's organization

GET /projects

Code samples

curl -X GET https://localhost:9243/api/v0.9/projects \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Accept: application/json'

Retrieves all projects belonging to the organization specified in the JWT token. Organization ID is automatically extracted from the token.

Authentication

Parameters

Name In Type Required Description
limit query integer false Maximum number of items to return per page.
offset query integer false Zero-based index of the first item to return.
sortBy query string false Field to sort the collection by. An unrecognized value falls back to the default sort (createdAt).
sortOrder query string false Sort direction applied to sortBy.
query query string false Case-insensitive substring filter matched against the resource id (handle).

Enumerated Values

Parameter Value
sortBy name
sortBy createdAt
sortOrder asc
sortOrder desc

Example responses

200 Response

{
  "count": 2,
  "list": [
    {
      "id": "default-project",
      "displayName": "Default Project",
      "description": "This is the default project for development",
      "organizationId": "acme",
      "createdBy": "john.doe",
      "updatedBy": "john.doe",
      "createdAt": "2023-10-12T10:30:00Z",
      "updatedAt": "2023-10-12T10:30:00Z"
    }
  ],
  "pagination": {
    "total": 10,
    "offset": 0,
    "limit": 10
  }
}

401 Response

{
  "status": "error",
  "code": "UNAUTHORIZED",
  "message": "Authorization header is required, or the token is invalid or expired."
}

404 Response

{
  "status": "error",
  "code": "NOT_FOUND",
  "message": "The specified resource does not exist."
}

500 Response

{
  "status": "error",
  "code": "INTERNAL_ERROR",
  "message": "An unexpected error occurred.",
  "trackingId": "4f1c6f2e-8a4b-4c93-b1de-9f2f6f0c2a11"
}

Responses

Status Meaning Description Schema
200 OK Projects retrieved successfully ProjectListResponse
401 Unauthorized Unauthorized. Authentication credentials are missing or invalid. Error
404 Not Found Not Found. The specified resource does not exist. Error
500 Internal Server Error Internal Server Error. Error

Get project by ID

GET /projects/{projectId}

Code samples

curl -X GET https://localhost:9243/api/v0.9/projects/{projectId} \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Accept: application/json'

Retrieves a specific project by its ID (handle). Access is validated against the organization in the JWT token to ensure users can only access projects in their organization.

Authentication

Parameters

Name In Type Required Description
projectId path string true Project ID consisting of the handle (unique slug identifier) of the Project.

Detailed descriptions

projectId: Project ID consisting of the handle (unique slug identifier) of the Project.

Example responses

200 Response

{
  "id": "default-project",
  "displayName": "Default Project",
  "description": "This is the default project for development",
  "organizationId": "acme",
  "createdBy": "john.doe",
  "updatedBy": "john.doe",
  "createdAt": "2023-10-12T10:30:00Z",
  "updatedAt": "2023-10-12T10:30:00Z"
}

400 Response

{
  "status": "error",
  "code": "VALIDATION_FAILED",
  "message": "The request failed validation.",
  "errors": [
    {
      "field": "<name of the offending field>",
      "message": "<reason this field failed validation>"
    }
  ]
}

401 Response

{
  "status": "error",
  "code": "UNAUTHORIZED",
  "message": "Authorization header is required, or the token is invalid or expired."
}

404 Response

{
  "status": "error",
  "code": "NOT_FOUND",
  "message": "The specified resource does not exist."
}

500 Response

{
  "status": "error",
  "code": "INTERNAL_ERROR",
  "message": "An unexpected error occurred.",
  "trackingId": "4f1c6f2e-8a4b-4c93-b1de-9f2f6f0c2a11"
}

Responses

Status Meaning Description Schema
200 OK Project retrieved successfully Project
400 Bad Request Bad Request. Invalid request or validation error. Error
401 Unauthorized Unauthorized. Authentication credentials are missing or invalid. Error
404 Not Found Not Found. The specified resource does not exist. Error
500 Internal Server Error Internal Server Error. Error

Update project

PUT /projects/{projectId}

Code samples

curl -X PUT https://localhost:9243/api/v0.9/projects/{projectId} \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d @payload.json

Updates an existing project's name. Access is validated against the organization in the JWT token.

Payload

{
  "displayName": "Default Project",
  "description": "This is the default project for development"
}

Authentication

Parameters

Name In Type Required Description
projectId path string true Project ID consisting of the handle (unique slug identifier) of the Project.
body body Project true none

Detailed descriptions

projectId: Project ID consisting of the handle (unique slug identifier) of the Project.

Example responses

200 Response

{
  "id": "default-project",
  "displayName": "Default Project",
  "description": "This is the default project for development",
  "organizationId": "acme",
  "createdBy": "john.doe",
  "updatedBy": "john.doe",
  "createdAt": "2023-10-12T10:30:00Z",
  "updatedAt": "2023-10-12T10:30:00Z"
}

400 Response

{
  "status": "error",
  "code": "VALIDATION_FAILED",
  "message": "The request failed validation.",
  "errors": [
    {
      "field": "<name of the offending field>",
      "message": "<reason this field failed validation>"
    }
  ]
}

401 Response

{
  "status": "error",
  "code": "UNAUTHORIZED",
  "message": "Authorization header is required, or the token is invalid or expired."
}

403 Response

{
  "status": "error",
  "code": "FORBIDDEN",
  "message": "You do not have permission to perform this action."
}

404 Response

{
  "status": "error",
  "code": "NOT_FOUND",
  "message": "The specified resource does not exist."
}

409 Response

{
  "status": "error",
  "code": "CONFLICT",
  "message": "The request conflicts with the current state of the resource."
}

500 Response

{
  "status": "error",
  "code": "INTERNAL_ERROR",
  "message": "An unexpected error occurred.",
  "trackingId": "4f1c6f2e-8a4b-4c93-b1de-9f2f6f0c2a11"
}

Responses

Status Meaning Description Schema
200 OK Project updated successfully Project
400 Bad Request Bad Request. Invalid request or validation error. Error
401 Unauthorized Unauthorized. Authentication credentials are missing or invalid. Error
403 Forbidden Forbidden. The authenticated user does not have permission to access this resource. Error
404 Not Found Not Found. The specified resource does not exist. Error
409 Conflict Conflict. The request conflicts with the current state of the resource. Error
500 Internal Server Error Internal Server Error. Error

Delete project

DELETE /projects/{projectId}

Code samples

curl -X DELETE https://localhost:9243/api/v0.9/projects/{projectId} \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Accept: application/json'

Deletes a specific project by its handle (unique slug identifier). Access is validated against the organization in the JWT token.

Authentication

Parameters

Name In Type Required Description
projectId path string true Project ID consisting of the handle (unique slug identifier) of the Project.

Detailed descriptions

projectId: Project ID consisting of the handle (unique slug identifier) of the Project.

Example responses

400 Response

{
  "status": "error",
  "code": "VALIDATION_FAILED",
  "message": "The request failed validation.",
  "errors": [
    {
      "field": "<name of the offending field>",
      "message": "<reason this field failed validation>"
    }
  ]
}

401 Response

{
  "status": "error",
  "code": "UNAUTHORIZED",
  "message": "Authorization header is required, or the token is invalid or expired."
}

403 Response

{
  "status": "error",
  "code": "FORBIDDEN",
  "message": "You do not have permission to perform this action."
}

404 Response

{
  "status": "error",
  "code": "NOT_FOUND",
  "message": "The specified resource does not exist."
}

500 Response

{
  "status": "error",
  "code": "INTERNAL_ERROR",
  "message": "An unexpected error occurred.",
  "trackingId": "4f1c6f2e-8a4b-4c93-b1de-9f2f6f0c2a11"
}

Responses

Status Meaning Description Schema
204 No Content Project deleted successfully None
400 Bad Request Bad Request. Invalid request or validation error. Error
401 Unauthorized Unauthorized. Authentication credentials are missing or invalid. Error
403 Forbidden Forbidden. The authenticated user does not have permission to access this resource. Error
404 Not Found Not Found. The specified resource does not exist. Error
500 Internal Server Error Internal Server Error. Error