AimableDocs
DocsAPI ReferenceRelease Notes

Artifacts

Updated 9 July 2026

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.

bash
curl -X GET \
  'https://api.aimable.com/api/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):

json
{
  "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.

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

Response (200 OK):

json
{
  "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.

bash
curl -X GET \
  'https://api.aimable.com/api/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.

bash
curl -X POST \
  'https://api.aimable.com/api/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):

json
{
  "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).

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

Response (200 OK):

json
[
  {
    "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"
  }
]

See Authentication & errors for request authentication and the standard error responses.

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

See also