Multi-workspace scoping, brand isolation, header precedence, and access conflicts.

Aidelly supports multi-workspace organization for teams and agencies. The API uses HTTP headers to scope requests to a specific workspace and brand.

Headers

Every request must include a workspace header and may optionally specify a brand:

curl "$AIDELLY_API_BASE/posts" \
  -H "Authorization: Bearer $AIDELLY_API_KEY" \
  -H "x-aidelly-workspace-id: ws_abc123def456" \
  -H "x-aidelly-brand-id: br_xyz789"

`x-aidelly-workspace-id` (required)

The workspace UUID. Scopes the request to all resources in that workspace, including all brands within it.

Format: UUID
Example: f47ac10b-58cc-4372-a567-0e02b2c3d479
Behavior: If omitted or empty, the API returns 400 PUBLIC_API_WORKSPACE_REQUIRED

`x-aidelly-brand-id` (optional)

The brand UUID within the workspace. Narrows the scope to a single brand's resources.

Format: UUID or string
Example: br_primary_brand
Behavior: If omitted, operations apply to all brands in the workspace. If the brand does not exist in the workspace, the API returns 404 PUBLIC_API_BRAND_NOT_FOUND

Access Rules

Workspace Access

Your API key is associated with a workspace (either workspace-scoped or personal workspace). You may only make requests scoped to workspaces you have access to.

If you attempt to access a workspace you don't have access to, the API returns:

{
  "success": false,
  "error": {
    "code": "PUBLIC_API_SCOPE_FORBIDDEN",
    "message": "Key does not have access to this workspace."
  },
  "request_id": "uuid"
}

Brand Access

A brand must belong to the specified workspace. If you specify a brand ID that does not exist in the workspace:

{
  "success": false,
  "error": {
    "code": "PUBLIC_API_BRAND_NOT_FOUND",
    "message": "Brand not found in this workspace."
  },
  "request_id": "uuid"
}

Scope Precedence

When both headers are provided, the API applies filters in this order:

Workspace: narrows to resources in that workspace
Brand: further narrows to resources in that brand

Example: Creating a post scoped to both workspace and brand:

curl -X POST "$AIDELLY_API_BASE/posts" \
  -H "Authorization: Bearer $AIDELLY_API_KEY" \
  -H "x-aidelly-workspace-id: ws_abc123def456" \
  -H "x-aidelly-brand-id: br_xyz789" \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "linkedin",
    "content_text": "Hello from Brand XYZ"
  }'

The post is created and associated only with that brand. When listing posts, you will see:

# Posts for all brands in workspace
curl "$AIDELLY_API_BASE/posts?from=2026-02-01T00:00:00Z&to=2026-02-28T23:59:59Z&limit=25" \
  -H "x-aidelly-workspace-id: ws_abc123def456"

# Posts for Brand XYZ only
curl "$AIDELLY_API_BASE/posts?from=2026-02-01T00:00:00Z&to=2026-02-28T23:59:59Z&limit=25" \
  -H "x-aidelly-workspace-id: ws_abc123def456" \
  -H "x-aidelly-brand-id: br_xyz789"

Workspace Query Endpoint

To discover which workspaces and brands your API key can access:

curl "$AIDELLY_API_BASE/workspaces" \
  -H "Authorization: Bearer $AIDELLY_API_KEY"

Response:

{
  "success": true,
  "data": {
    "workspaces": [
      {
        "id": "ws_abc123def456",
        "name": "My Agency",
        "brands": [
          {
            "id": "br_xyz789",
            "name": "Brand A"
          },
          {
            "id": "br_abc111",
            "name": "Brand B"
          }
        ]
      }
    ]
  },
  "request_id": "uuid"
}

Use this endpoint to resolve workspace and brand IDs for your integration.

Common Patterns

Multi-brand Publishing

Publish the same post content to multiple brands:

# Fetch all brands
WORKSPACES=$(curl -s "$AIDELLY_API_BASE/workspaces" \
  -H "Authorization: Bearer $AIDELLY_API_KEY")

# For each brand, create a post
for BRAND_ID in $(echo $WORKSPACES | jq -r '.data.workspaces[0].brands[].id'); do
  curl -X POST "$AIDELLY_API_BASE/posts" \
    -H "Authorization: Bearer $AIDELLY_API_KEY" \
    -H "x-aidelly-workspace-id: ws_abc123def456" \
    -H "x-aidelly-brand-id: $BRAND_ID" \
    -H "Idempotency-Key: post-$BRAND_ID-001" \
    -d '{
      "platform": "linkedin",
      "content_text": "Hello everyone!"
    }'
done

Agency Scenario

An agency has multiple workspaces, one per client. Each workspace has one or more brands. Use the workspace/brand headers to isolate data per client:

# Client A's workspace
curl "$AIDELLY_API_BASE/posts?page=1&limit=10" \
  -H "x-aidelly-workspace-id: ws_client_a_uuid"

# Client B's workspace
curl "$AIDELLY_API_BASE/posts?page=1&limit=10" \
  -H "x-aidelly-workspace-id: ws_client_b_uuid"

Workspaces and Brands