AimableDocs
DocsAPI Reference

Projects

Projects API

The Projects domain in the Aimable Platform API (v0.1.0) enables teams to organize work within a shared space. A project represents a distinct unit of collaboration—such as a product launch, campaign, or development sprint—that can have its own members, roles, and metadata. Projects are scoped to a space, allowing fine-grained access control and resource isolation.

Managing projects via the API allows automation of team workflows, integration with external tools, and dynamic permission management.

Key Concepts

  • Project: A container for collaborative work, with a name, description, and timestamps.
  • Space: The parent container for projects. All projects belong to exactly one space.
  • Member: A user (principal) assigned to a project with a specific role (role_id).
  • Idempotency-Key: Optional header to ensure safe retries when creating or modifying resources.

Authentication is required for all endpoints using either a Bearer token or X-API-Key header.

Common Workflows

1. Create a Project and Add Members

Step 1: Create a new project

curl -X POST 'https://api.aimable.com/api-proxy/v1/spaces/123e4567-e89b-12d3-a456-426614174000/projects' \
  -H 'Authorization: Bearer <your-access-token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "name": "Website Redesign Q3",
    "description": {
      "summary": "Redesign company website for improved UX and SEO"
    }
  }'

Response (201 Created):

{
  "id": "a1b2c3d4-e5f6-7890-g1h2-i3j4k5l6m7n8",
  "tenant_id": "t1u2v3w4-x5y6-z7a8-b9c0-d1e2f3g4h5i6",
  "space_id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "Website Redesign Q3",
  "description": {
    "summary": "Redesign company website for improved UX and SEO"
  },
  "created_by": "u1234567-89ab-cdef-0123-456789abcdef",
  "status": "active",
  "created_at": "2025-04-05T10:00:00Z",
  "updated_at": "2025-04-05T10:00:00Z"
}

Step 2: Add a member to the project

curl -X POST 'https://api.aimable.com/api-proxy/v1/spaces/123e4567-e89b-12d3-a456-426614174000/projects/a1b2c3d4-e5f6-7890-g1h2-i3j4k5l6m7n8/members' \
  -H 'Authorization: Bearer <your-access-token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "principal_id": "u8765432-10fe-dcba-9876-543210fedcba",
    "role_id": "r0987654-32dc-ba98-7654-3210fedcba98"
  }'

Response (201 Created):

{
  "tenant_id": "t1u2v3w4-x5y6-z7a8-b9c0-d1e2f3g4h5i6",
  "project_id": "a1b2c3d4-e5f6-7890-g1h2-i3j4k5l6m7n8",
  "principal_id": "u8765432-10fe-dcba-9876-543210fedcba",
  "role_id": "r0987654-32dc-ba98-7654-3210fedcba98",
  "status": "active",
  "created_at": "2025-04-05T10:05:00Z",
  "updated_at": "2025-04-05T10:05:00Z"
}

2. List and Update a Project

List all projects in a space:

curl -X GET 'https://api.aimable.com/api-proxy/v1/spaces/123e4567-e89b-12d3-a456-426614174000/projects' \
  -H 'Authorization: Bearer <your-access-token>'

Response (200 OK):

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-g1h2-i3j4k5l6m7n8",
      "name": "Website Redesign Q3",
      "status": "active",
      "created_at": "2025-04-05T10:00:00Z",
      "updated_at": "2025-04-05T10:00:00Z"
    }
  ],
  "meta": {
    "has_more": false
  }
}

Update project description:

curl -X PATCH 'https://api.aimable.com/api-proxy/v1/spaces/123e4567-e89b-12d3-a456-426614174000/projects/a1b2c3d4-e5f6-7890-g1h2-i3j4k5l6m7n8' \
  -H 'Authorization: Bearer <your-access-token>' \
  -H 'Content-Type: application/json' \
  -d '{
    "description": {
      "summary": "Updated scope to include mobile optimization"
    }
  }'

Authentication & Error Handling

All endpoints require authentication. Use either:

  • Authorization: Bearer <token>
  • X-API-Key: <api-key>

Common errors:

  • 401 Unauthorized: Missing or invalid credentials.
  • 403 Forbidden: User lacks permissions for the space or project.
  • 422 Unprocessable Entity: Invalid input (e.g., malformed UUID or missing required field). Inspect the detail array for specifics.

Example validation error:

{
  "detail": [
    {
      "loc": ["body", "name"],
      "msg": "Field required",
      "type": "missing"
    }
  ]
}

Use these patterns to build reliable integrations with robust error recovery and idempotent operations.

Related Endpoints