Threads API

Introduction

The Threads API provides comprehensive thread management capabilities for PromptQL conversations. This includes creating, retrieving, updating, and deleting threads, as well as advanced features like thread sharing, feedback collection, evaluation, and pinned threads management.

Base URL

Thread endpoints use the following base URL:

https://promptql.ddn.hasura.app/

Private DDN Endpoint

For Private DDN setups the endpoint will change to use the fully qualified domain name (FQDN) for the project assigned by the control plane. For example:

https://promptql.<FQDN>/

You can find your API endpoint in the project's settings under PromptQL API Endpoint.

Authentication

Thread endpoints use two different authentication models depending on the operation:

User-Scoped Operations (JWT Bearer Token Required)

These endpoints manage user-owned resources and require JWT authentication:

Authorization: Bearer <jwt-token>
Content-Type: application/json

Endpoints:

• Thread management (GET/PATCH/DELETE /threads/{thread_id} when using user auth)
• Shared thread operations (/threads/{thread_id}/shared)
• Pinned threads (/projects/{project_id}/pinned-threads) - explicitly rejects API keys

Project-Scoped Operations (API Key Accepted)

These endpoints access shared project resources and accept PromptQL API keys:

Authorization: Bearer <your-promptql-api-key>
Content-Type: application/json

Endpoints:

• Thread reading (/threads/{thread_id}, /api-threads/{thread_id}) when using API key
• Thread listing (/threads, /api-threads)
• Thread evaluation (/threads/{thread_id}/evaluate)
• Thread feedback (/threads/{thread_id}/feedback)

Getting JWT Tokens

For user-scoped operations, you need to obtain a JWT token using your Personal Access Token (PAT) or Project Service Account Token. See the Authentication Guide for detailed instructions on how to get JWT tokens.

Thread Management

Get Threads

Retrieve a list of threads with optional filtering.

GET /threads

Query Parameters

Parameter	Type	Required	Description
project_id	string	No	Filter threads by project UUID
build_id	string	No	Filter threads by build UUID. If not provided, threads from the project's production endpoint are returned
user_id	string	No	Filter threads by user UUID
from_created_at	datetime	No	Filter threads created after this timestamp
to_created_at	datetime	No	Filter threads created before this timestamp
title_contains	string	No	Filter threads where title contains this text

Response

{
  "threads": [
    {
      "thread_id": "123e4567-e89b-12d3-a456-426614174000",
      "title": "Data Analysis Discussion",
      "created_at": "2024-01-15T10:30:00Z",
      "updated_at": "2024-01-15T11:45:00Z",
      "user_id": "user-uuid",
      "project_id": "project-uuid"
    }
  ],
  "total_count": 1
}

Get Thread

Retrieve a specific thread by ID.

GET /threads/{thread_id}

Path Parameters

Parameter	Type	Required	Description
thread_id	string	Yes	UUID of the thread to retrieve

Response

{
  "thread_id": "123e4567-e89b-12d3-a456-426614174000",
  "title": "Data Analysis Discussion",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T11:45:00Z",
  "user_id": "user-uuid",
  "project_id": "project-uuid",
  "interactions": [
    {
      "interaction_id": "interaction-uuid",
      "user_message": "What insights can you provide about our sales data?",
      "assistant_response": "Based on the sales data, I can see several key trends...",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ]
}

Update Thread

Update thread properties like title.

PATCH /threads/{thread_id}

Path Parameters

Parameter	Type	Required	Description
thread_id	string	Yes	UUID of the thread to update

Request Body

{
  "title": "Updated Thread Title"
}

Request Fields

Field	Type	Required	Description
title	string	No	New title for thread

Response

{
  "thread_id": "123e4567-e89b-12d3-a456-426614174000",
  "title": "Updated Thread Title",
  "updated_at": "2024-01-15T12:00:00Z",
  "status": "updated"
}

Delete Thread

Delete a thread and all its associated data.

DELETE /threads/{thread_id}

Path Parameters

Parameter	Type	Required	Description
thread_id	string	Yes	UUID of the thread to delete

Response

{
  "thread_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "deleted",
  "message": "Thread deleted successfully"
}

Thread Sharing

Share Thread

Make a thread accessible to project collaborators.

PUT /threads/{thread_id}/shared

Path Parameters

Parameter	Type	Required	Description
thread_id	string	Yes	UUID of the thread to share

Request Body

{
  "shared_interaction_id": "interaction-uuid-to-share-up-to"
}

Request Fields

Field	Type	Required	Description
shared_interaction_id	string	No	Share thread up to this interaction ID (optional)

Response

{
  "thread_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "shared",
  "shared_url": "https://promptql.ddn.hasura.app/shared/123e4567-e89b-12d3-a456-426614174000",
  "shared_interaction_id": "interaction-uuid"
}

Get Shared Thread

Retrieve a shared thread. Access is granted to project collaborators.

GET /threads/{thread_id}/shared

Path Parameters

Parameter	Type	Required	Description
thread_id	string	Yes	UUID of the shared thread to retrieve

Response

{
  "thread_id": "123e4567-e89b-12d3-a456-426614174000",
  "title": "Shared Data Analysis",
  "shared_at": "2024-01-15T10:30:00Z",
  "shared_interaction_id": "interaction-uuid",
  "interactions": [
    {
      "interaction_id": "interaction-uuid",
      "user_message": "What insights can you provide?",
      "assistant_response": "Based on the data...",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ]
}

Unshare Thread

Remove sharing access for a thread.

DELETE /threads/{thread_id}/shared

Path Parameters

Parameter	Type	Required	Description
thread_id	string	Yes	UUID of the thread to unshare

Response

{
  "thread_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "unshared",
  "message": "Thread sharing removed successfully"
}

API Threads

API threads are threads created through API interactions rather than the Playground.

Get API Threads

Retrieve API-created threads with optional filtering.

GET /api-threads

Query Parameters

Parameter	Type	Required	Description
project_id	string	No	Filter threads by project UUID
from_created_at	datetime	No	Filter threads created after this timestamp
to_created_at	datetime	No	Filter threads created before this timestamp
title_contains	string	No	Filter threads where title contains this text

Response

{
  "api_threads": [
    {
      "thread_id": "123e4567-e89b-12d3-a456-426614174000",
      "title": "API Generated Analysis",
      "created_at": "2024-01-15T10:30:00Z",
      "project_id": "project-uuid",
      "api_key_id": "api-key-uuid"
    }
  ],
  "total_count": 1
}

Get API Thread

Retrieve a specific API thread by ID.

GET /api-threads/{thread_id}

Path Parameters

Parameter	Type	Required	Description
thread_id	string	Yes	UUID of the API thread to retrieve

Response

{
  "thread_id": "123e4567-e89b-12d3-a456-426614174000",
  "title": "API Generated Analysis",
  "created_at": "2024-01-15T10:30:00Z",
  "project_id": "project-uuid",
  "api_key_id": "api-key-uuid",
  "interactions": [
    {
      "interaction_id": "interaction-uuid",
      "user_message": "Analyze this data",
      "assistant_response": "Here's the analysis...",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ]
}

Error Responses

All thread endpoints may return the following error responses:

• 404 Not Found - Thread not found or user doesn't have access
• 422 Validation Error - Invalid request parameters or body

Validation Error Format

{
  "detail": [
    {
      "loc": ["field_name"],
      "msg": "error message",
      "type": "error_type"
    }
  ]
}

Pinned Threads

Manage pinned threads for quick access within a project.

Get Pinned Threads

Get a user's pinned thread IDs for a specific project.

GET /projects/{project_id}/pinned-threads

Path Parameters

Parameter	Type	Required	Description
project_id	string	Yes	UUID of the project

Response

{
  "project_id": "project-uuid",
  "pinned_thread_ids": ["123e4567-e89b-12d3-a456-426614174000", "987fcdeb-51a2-43d7-8f9e-123456789abc"]
}

Update Pinned Threads

Replace all pinned threads for a user in a specific project.

POST /projects/{project_id}/pinned-threads

Path Parameters

Parameter	Type	Required	Description
project_id	string	Yes	UUID of the project

Request Body

{
  "thread_ids": ["123e4567-e89b-12d3-a456-426614174000", "987fcdeb-51a2-43d7-8f9e-123456789abc"]
}

Response

{
  "project_id": "project-uuid",
  "pinned_thread_ids": ["123e4567-e89b-12d3-a456-426614174000", "987fcdeb-51a2-43d7-8f9e-123456789abc"],
  "status": "updated"
}

Add Pinned Thread

Add a single thread to pinned threads.

PUT /projects/{project_id}/pinned-threads

Path Parameters

Parameter	Type	Required	Description
project_id	string	Yes	UUID of the project

Request Body

{
  "thread_id": "123e4567-e89b-12d3-a456-426614174000"
}

Response

{
  "project_id": "project-uuid",
  "thread_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "pinned"
}

Remove Pinned Thread

Remove a single thread from pinned threads.

DELETE /projects/{project_id}/pinned-threads

Path Parameters

Parameter	Type	Required	Description
project_id	string	Yes	UUID of the project

Request Body

{
  "thread_id": "123e4567-e89b-12d3-a456-426614174000"
}

Response

{
  "project_id": "project-uuid",
  "thread_id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "unpinned"
}

Thread Evaluation

Evaluate thread interactions for quality and reliability scoring.

Evaluate Thread

Evaluate a specific interaction within a thread.

POST /threads/{thread_id}/evaluate

Path Parameters

Parameter	Type	Required	Description
thread_id	string	Yes	UUID of the thread to evaluate

Request Body

{
  "ddn_headers": {
    "x-hasura-ddn-token": "<YOUR_DDN_AUTH_TOKEN>"
  },
  "interaction_id": "interaction-uuid",
  "recompute": false
}

Request Fields

Field	Type	Required	Description
ddn_headers	object	Yes	Headers to pass through to DDN
interaction_id	string	No	Specific interaction to evaluate (optional)
recompute	boolean	No	Force recomputation of evaluation (default: false)

Response

{
  "thread_id": "123e4567-e89b-12d3-a456-426614174000",
  "interaction_id": "interaction-uuid",
  "evaluation": {
    "version": "v1",
    "reliability_score": 0.85,
    "notes": ["Response was accurate and well-structured", "Code execution completed successfully"]
  }
}

Thread Feedback

Collect and retrieve feedback on thread interactions.

Submit Thread Feedback

Submit feedback for a thread or specific interaction.

POST /threads/{thread_id}/feedback

Path Parameters

Parameter	Type	Required	Description
thread_id	string	Yes	UUID of the thread to give feedback on

Request Body

{
  "feedback": 1,
  "interaction_id": "interaction-uuid",
  "action_id": "action-uuid",
  "detail": "The response was very helpful and accurate"
}

Request Fields

Field	Type	Required	Description
feedback	integer	Yes	Feedback score (typically -1, 0, or 1)
interaction_id	string	No	Specific interaction being rated
action_id	string	No	Specific action within interaction being rated
detail	string	No	Additional feedback details

Response

{
  "thread_id": "123e4567-e89b-12d3-a456-426614174000",
  "feedback_id": "feedback-uuid",
  "status": "submitted",
  "message": "Feedback submitted successfully"
}

Get Thread Feedback

Retrieve feedback for a thread or specific interaction.

GET /threads/{thread_id}/feedback

Path Parameters

Parameter	Type	Required	Description
thread_id	string	Yes	UUID of the thread to get feedback for

Query Parameters

Parameter	Type	Required	Description
interaction_id	string	No	Filter feedback for specific interaction

Response

{
  "thread_id": "123e4567-e89b-12d3-a456-426614174000",
  "feedback": [
    {
      "feedback_id": "feedback-uuid",
      "feedback": 1,
      "interaction_id": "interaction-uuid",
      "action_id": "action-uuid",
      "detail": "The response was very helpful and accurate",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ]
}