Threads

Overview

Threads keep every Alfa API exchange stateful so you can execute long-running research, pause work, and resume with full context. Each thread stores metadata, message history, task progress, and structured artifacts generated during analysis.

• Use POST /v2/threads to create a new thread and GET /v2/threads to discover existing ones.
• Send instructions with POST /v2/threads/{thread_id}/messages and stream events using gRPC or SSE streaming.
• See chat history and structured data table outputs with GET /v2/threads/{thread_id}/messages and GET /v2/threads/{thread_id}/artifacts/{artifact_id} respectively.

Thread lifecycle

Create and manage threads

Threads are lightweight resources. You can list, rename, or delete them without touching other workloads.

1
import os
2
import requests
3
4
BASE_URL = os.getenv("ALFA_API_BASE_URL", "https://sandbox.api.boosted.ai")
5
ACCESS_TOKEN = os.environ["ALFA_ACCESS_TOKEN"]
6
7
def auth_headers() -> dict:
8
    return {"Authorization": f"Bearer {ACCESS_TOKEN}", "Content-Type": "application/json"}
9
10
def create_thread(thread_name: str) -> str:
11
    resp = requests.post(
12
        f"{BASE_URL}/v2/threads",
13
        headers=auth_headers(),
14
        json={"thread_name": thread_name},
15
        timeout=30,
16
    )
17
    resp.raise_for_status()
18
    return resp.json()["thread_id"]
19
20
def list_threads() -> list[dict]:
21
    resp = requests.get(f"{BASE_URL}/v2/threads", headers=auth_headers(), timeout=30)
22
    resp.raise_for_status()
23
    return resp.json()["threads"]
24
25
def rename_thread(thread_id: str, new_name: str) -> None:
26
    payload = {"name": new_name}
27
    resp = requests.patch(
28
        f"{BASE_URL}/v2/threads/{thread_id}",
29
        headers=auth_headers(),
30
        json=payload,
31
        timeout=30,
32
    )
33
    resp.raise_for_status()

Send messages

POST /v2/threads/{thread_id}/messages validates the caller has access to the thread, queues the task, and returns immediately. To receive real-time updates, use gRPC or SSE streaming.

1
import os
2
import requests
3
4
BASE_URL = os.getenv("ALFA_API_BASE_URL", "https://sandbox.api.boosted.ai")
5
ACCESS_TOKEN = os.environ["ALFA_ACCESS_TOKEN"]
6
7
def auth_headers():
8
    return {"Authorization": f"Bearer {ACCESS_TOKEN}"}
9
10
def send_message(thread_id: str, message: str) -> dict:
11
    resp = requests.post(
12
        f"{BASE_URL}/v2/threads/{thread_id}/messages",
13
        headers=auth_headers(),
14
        data={"message": message},
15
        timeout=30,
16
    )
17
    resp.raise_for_status()
18
    return resp.json()

Retrieve history and artifacts

Use the history endpoint to build up the log of chat messages sent over the course of a conversation, and the artifacts endpoint to retrieve structured data output.

1
import os
2
import requests
3
4
BASE_URL = os.getenv("ALFA_API_BASE_URL", "https://sandbox.api.boosted.ai")
5
ACCESS_TOKEN = os.environ["ALFA_ACCESS_TOKEN"]
6
7
def auth_headers():
8
    return {"Authorization": f"Bearer {ACCESS_TOKEN}", "Content-Type": "application/json"}
9
10
def get_history(thread_id: str, *, start_index: int = 0, limit_num: int = 50) -> list[dict]:
11
    params = {"start_index": start_index, "limit_num": limit_num}
12
    resp = requests.get(
13
        f"{BASE_URL}/v2/threads/{thread_id}/messages",
14
        headers=auth_headers(),
15
        params=params,
16
        timeout=30,
17
    )
18
    resp.raise_for_status()
19
    return resp.json()["messages"]
20
21
def get_artifact(thread_id: str, artifact_id: str) -> dict:
22
    resp = requests.get(
23
        f"{BASE_URL}/v2/threads/{thread_id}/artifacts/{artifact_id}",
24
        headers=auth_headers(),
25
        timeout=30,
26
    )
27
    resp.raise_for_status()
28
    return resp.json()["artifact"]

Tie artifact IDs to the message_id returned by GET /v2/threads/{thread_id}/messages so you can render both the prose answer and the structured data.

Citations

Alfa responses include citations that link claims in the generated text back to their source material. Citations appear in three places:

• Messages — each message returned by GET /v2/threads/{thread_id}/messages includes a citations array with source metadata.
• Streaming events — both SSE and gRPC streams deliver citations alongside message chunks and final messages as they arrive.
• Artifacts — structured data outputs (tables, charts) can carry their own citation references tied to individual data points.

Each citation carries a citation_type that identifies the source category (such as web, news_development, or document) along with type-specific fields like URLs, snippet positions, and article counts. Use this metadata to build source attribution UI — for example, rendering footnotes, expandable source cards, or inline reference links for end users.

Upload user files to a thread

Attach supporting documents directly to a thread so the model can cite them during follow-up prompts. The endpoint expects multipart form data and associates the uploaded blob with the specified thread.

1
import os
2
import requests
3
4
BASE_URL = os.getenv("ALFA_API_BASE_URL", "https://sandbox.api.boosted.ai")
5
ACCESS_TOKEN = os.environ["ALFA_ACCESS_TOKEN"]
6
7
def upload_user_file(thread_id: str, file_path: str) -> dict:
8
    with open(file_path, "rb") as fh:
9
        files = {"file": fh}
10
        resp = requests.post(
11
            f"{BASE_URL}/v2/threads/{thread_id}/files",
12
            headers={"Authorization": f"Bearer {ACCESS_TOKEN}"},
13
            files=files,
14
            timeout=60,
15
        )
16
    resp.raise_for_status()
17
    return resp.json()
18
19
response = upload_user_file(thread_id, "documents/q2.pdf")
20
print("Uploaded file:", response["file_id"])

Cancel a running task

Use the cancellation endpoint to stop the currently processing message whenever a user changes their mind. The API records a “User cancelled” entry in the thread so downstream reviewers can see why work halted.

1
def cancel_thread_task(thread_id: str) -> None:
2
    resp = requests.delete(
3
        f"{BASE_URL}/v2/threads/{thread_id}/task",
4
        headers=auth_headers(),
5
        timeout=15,
6
    )
7
    resp.raise_for_status()
8
9
cancel_thread_task(thread_id)