AimableDocs
DocsAPI Reference

Artifacts

Introduction to Artifacts

Artifacts in the FastAPI platform represent digital assets or documents associated with a specific space. These artifacts are crucial for managing, sharing, and processing data within collaborative environments. They can be anything from documents, images, or any other type of file that needs to be stored and accessed within a space. Understanding how to interact with artifacts is essential for developers looking to build applications that leverage FastAPI's capabilities for document management and collaboration.

Key Concepts

Spaces and Artifacts

  • Space: A logical container for organizing artifacts. Each space is identified by a unique space_id.
  • Artifact: A digital asset within a space. Each artifact is identified by a unique artifact_id.

Authentication

Most endpoints require an X-API-Key for authentication. This key should be included in the request header to ensure secure access to the API.

Pagination

When listing artifacts, the API supports pagination through the cursor and limit query parameters. This allows for efficient data retrieval, especially when dealing with large datasets.

Common Workflows

Listing Artifacts

To retrieve a list of artifacts within a specific space, use the following endpoint:

curl -X GET "https://api.example.com/v1/spaces/{space_id}/artifacts" \
     -H "X-API-Key: your_api_key"

You can filter the list by thread_id, document_type, or status. Use cursor and limit for pagination.

Retrieving an Artifact

To get details of a specific artifact, use:

curl -X GET "https://api.example.com/v1/spaces/{space_id}/artifacts/{artifact_id}" \
     -H "X-API-Key: your_api_key"

This call returns metadata about the artifact, such as its type, status, and associated threads.

Downloading an Artifact

To download the actual file of an artifact, use:

curl -X GET "https://api.example.com/v1/spaces/{space_id}/artifacts/{artifact_id}/download" \
     -H "X-API-Key: your_api_key" -o artifact_file.ext

This will save the artifact to your local machine.

Generating a New Artifact

To create a new artifact, use the following POST request:

curl -X POST "https://api.example.com/v1/spaces/{space_id}/artifacts/generate" \
     -H "Content-Type: application/json" \
     -H "X-API-Key: your_api_key" \
     -d '{"name": "New Artifact", "type": "document", "content": "Base64EncodedContent"}'

Ensure the request body is in JSON format and includes all necessary fields.

Listing Artifact Jobs

To view jobs associated with an artifact, such as processing tasks, use:

curl -X GET "https://api.example.com/v1/spaces/{space_id}/artifacts/{artifact_id}/jobs" \
     -H "X-API-Key: your_api_key"

Important Considerations

  • Authentication: Always include the X-API-Key in your requests to authenticate and authorize access.
  • Idempotency: When generating artifacts, consider using the Idempotency-Key header to prevent duplicate creations in case of network failures.
  • Error Handling: Implement robust error handling to manage potential issues such as invalid parameters or authentication failures.
  • Security: Ensure sensitive data is handled securely, especially when dealing with file uploads and downloads.

By understanding these concepts and workflows, developers can effectively manage artifacts within the FastAPI platform, enabling robust document management solutions.