AimableDocs
DocsAPI Reference

Threads

Introduction to Threads

In the FastAPI API, the "threads" domain is designed to facilitate communication within spaces, allowing users to create, manage, and interact with threaded conversations. Threads are essential for organizing discussions, enabling users to track conversations efficiently and maintain context over time. This documentation provides an overview of the available endpoints for managing threads and messages within a space and outlines common workflows for interacting with these resources.

Key Concepts and Entities

  • Space: A container for threads, identified by a space_id. Each space can host multiple threads.
  • Thread: A conversation thread within a space, identified by a thread_id. Threads can be listed, retrieved, updated, or archived.
  • Message: A single unit of communication within a thread. Messages can be listed or created within a thread.

Common Workflows

Listing Threads

To view all threads within a specific space, use the GET /v1/spaces/{space_id}/threads endpoint. This call returns a list of threads, allowing you to browse and select specific threads for further interaction.

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

Retrieving a Specific Thread

To access detailed information about a specific thread, use the GET /v1/spaces/{space_id}/threads/{thread_id} endpoint. This is useful for viewing the thread's metadata and current status.

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

Updating a Thread

To modify a thread's details, use the PATCH /v1/spaces/{space_id}/threads/{thread_id} endpoint. This allows you to update attributes such as the thread's title or status.

curl -X PATCH "https://api.example.com/v1/spaces/{space_id}/threads/{thread_id}" \
-H "X-API-Key: your_api_key" \
-H "Content-Type: application/json" \
-d '{"title": "Updated Thread Title"}'

Archiving a Thread

To archive a thread, making it inactive, use the DELETE /v1/spaces/{space_id}/threads/{thread_id} endpoint. This action is reversible, allowing threads to be restored if needed.

curl -X DELETE "https://api.example.com/v1/spaces/{space_id}/threads/{thread_id}" -H "X-API-Key: your_api_key"

Managing Messages

Listing Messages

To list all messages within a specific thread, use the GET /v1/spaces/{space_id}/threads/{thread_id}/messages endpoint. This is useful for reviewing the conversation history.

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

Creating a Message

To add a new message to a thread, use the POST /v1/spaces/{space_id}/threads/{thread_id}/messages endpoint. Ensure idempotency by including an Idempotency-Key header to prevent duplicate messages.

curl -X POST "https://api.example.com/v1/spaces/{space_id}/threads/{thread_id}/messages" \
-H "X-API-Key: your_api_key" \
-H "Idempotency-Key: unique_key" \
-H "Content-Type: application/json" \
-d '{"content": "This is a new message."}'

Creating the First Message in a Thread

To initiate a new thread with a message, use the POST /v1/spaces/{space_id}/threads/messages endpoint. This creates both the thread and its first message.

curl -X POST "https://api.example.com/v1/spaces/{space_id}/threads/messages" \
-H "X-API-Key: your_api_key" \
-H "Idempotency-Key: unique_key" \
-H "Content-Type: application/json" \
-d '{"content": "Starting a new conversation."}'

Important Considerations

  • Authentication: Most endpoints require an X-API-Key for authentication. Ensure that you have a valid API key to access these resources.
  • Idempotency: When creating messages, use the Idempotency-Key header to avoid duplicate entries.
  • Error Handling: Handle HTTP errors gracefully, checking for status codes and error messages to ensure robust application behavior.
  • Pagination: For endpoints that return lists, consider implementing pagination to manage large datasets efficiently.

By understanding these concepts and workflows, developers can effectively manage threaded conversations within the FastAPI platform, enhancing communication and collaboration in their applications.