AimableDocs
DocsAPI Reference

Artifacts

Artifacts API

The Artifacts API in the Aimable Platform enables you to manage and retrieve generated documents (artifacts) associated with a specific workspace or collaboration space. These artifacts can include reports, summaries, transcripts, or any other structured output generated by the platform in response to user interactions or automated processes.

Artifacts are tied to a space and optionally to a thread, allowing you to organize and retrieve content contextually. You can list, retrieve, download, and generate artifacts programmatically, making it ideal for integration into dashboards, document management systems, or AI-powered workflows.

Key Concepts

  • Space: A container for collaboration, often representing a project or team. Identified by a UUID (space_id).
  • Artifact: A generated document (e.g., PDF, text, JSON). Identified by a UUID (artifact_id).
  • Thread: A conversation or interaction sequence within a space that may produce artifacts.
  • Job: Background process that generates an artifact. Each artifact may have one or more associated jobs.

Common Workflows

1. List Artifacts in a Space

Retrieve all artifacts in a space, optionally filtered by thread, type, or status.

curl -X GET \
  'https://api.aimable.com/api-proxy/v1/spaces/123e4567-e89b-12d3-a456-426614174000/artifacts?thread_id=7a8b9c0d&document_type=summary&status=completed&limit=10' \
  -H 'Authorization: Bearer <your-access-token>' \
  -H 'X-API-Key: your-api-key'

Response (200 OK):

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-g1h2-i3j4k5l6m7n8",
      "document_type": "summary",
      "status": "completed",
      "thread_id": "7a8b9c0d",
      "created_at": "2023-10-05T14:48:00Z",
      "updated_at": "2023-10-05T14:48:05Z"
    }
  ],
  "cursor": "next-page-token"
}

Use cursor and limit for pagination.

2. Get a Specific Artifact

Fetch metadata about a specific artifact by its ID.

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

Response (200 OK):

{
  "id": "a1b2c3d4-e5f6-7890-g1h2-i3j4k5l6m7n8",
  "document_type": "transcript",
  "status": "completed",
  "thread_id": "7a8b9c0d",
  "file_size": 20480,
  "mime_type": "text/plain",
  "created_at": "2023-10-05T14:48:00Z",
  "updated_at": "2023-10-05T14:48:05Z"
}

3. Download an Artifact

Retrieve the raw content of an artifact.

curl -X GET \
  'https://api.aimable.com/api-proxy/v1/spaces/123e4567-e89b-12d3-a456-426614174000/artifacts/a1b2c3d4-e5f6-7890-g1h2-i3j4k5l6m7n8/download' \
  -H 'Authorization: Bearer <your-access-token>' \
  --output transcript.txt

This returns the file directly (e.g., text, PDF). The filename and format depend on the artifact.

4. Generate a New Artifact

Trigger the creation of a new artifact, such as a meeting summary or report.

curl -X POST \
  'https://api.aimable.com/api-proxy/v1/spaces/123e4567-e89b-12d3-a456-426614174000/artifacts/generate' \
  -H 'Authorization: Bearer <your-access-token>' \
  -H 'Idempotency-Key: abc123xyz' \
  -H 'Content-Type: application/json' \
  -d '{
    "thread_id": "7a8b9c0d",
    "document_type": "summary",
    "format": "pdf",
    "options": {
      "include_transcript": false,
      "branding": "light"
    }
  }'

Response (201 Created):

{
  "id": "b2c3d4e5-f6g7-8901-h2i3-j4k5l6m7n8o9",
  "document_type": "summary",
  "format": "pdf",
  "status": "processing",
  "thread_id": "7a8b9c0d",
  "created_at": "2023-10-05T15:00:00Z"
}

Use the returned id to poll for status or retrieve the result later.

5. List Jobs for an Artifact

Check the background jobs associated with an artifact (e.g., generation, conversion).

curl -X GET \
  'https://api.aimable.com/api-proxy/v1/spaces/123e4567-e89b-12d3-a456-426614174000/artifacts/b2c3d4e5-f6g7-8901-h2i3-j4k5l6m7n8o9/jobs' \
  -H 'Authorization: Bearer <your-access-token>'

Response (200 OK):

[
  {
    "job_id": "j1k2l3m4-n5o6-p7q8-r9s0-t1u2v3w4x5y6",
    "type": "generate_summary",
    "status": "completed",
    "started_at": "2023-10-05T15:00:05Z",
    "ended_at": "2023-10-05T15:00:30Z"
  }
]

Authentication & Error Handling

Authentication

All endpoints require authentication:

  • Use Authorization: Bearer <access_token> for user-level access.
  • Optionally include X-API-Key for service-level authentication.

Common Errors

  • 401 Unauthorized: Missing or invalid access token.
  • 403 Forbidden: Insufficient permissions for the space or artifact.
  • 422 Unprocessable Entity: Invalid parameters or request body.

Example 422 Response:

{
  "detail": [
    {
      "loc": ["query", "limit"],
      "msg": "Input should be less than or equal to 100",
      "type": "less_than_equal",
      "input": 150
    }
  ]
}

Best Practices

  • Use Idempotency-Key when generating artifacts to avoid duplicates on retries.
  • Poll the GET /artifacts/{id} endpoint to monitor generation status.
  • Use query filters (thread_id, document_type, status) to reduce payload size.

With the Artifacts API, you can seamlessly integrate document generation and retrieval into your applications, enabling powerful automation and content delivery workflows.

Related Endpoints