Skip to main content
Version: PromptQL

Execute Program API

Introduction​

Under the hood, PromptQL utilizes a set of built-in primitives, in conjunction with any custom business logic you've provided, to create small programs on top of your data.

These primitives pair relevant data or artifacts—represented as inputs or data—from your application with on-the-fly and context-aware instructions based on the thread between the user and PromptQL.

Summarize​

Example:
summaries = executor.summarize(
    instructions="""
    Create a concise summary of each reservation focusing on:
    - The restaurant name
    - Any special notes or important details
    Keep each summary to 1-2 sentences.
    """,
    inputs=reservation_texts
)

Extract​

Example:
extracted_info = executor.extract(
        json_schema=json_schema,
        instructions="""
        Extract any mentioned dietary requirements, special occasions, or seating preferences from the reservation notes.
        For dietary requirements, include any allergies, restrictions, or preferences mentioned.
        For special occasions, look for mentions of birthdays, anniversaries, celebrations etc.
        For seating preferences, identify if they specifically requested indoor, outdoor, bar seating etc.
        If any field is not mentioned, omit it from the output.
        """,
        inputs=notes_to_extract
    )

Classify​

Example:
classifications = executor.classify(
    instructions="""
    Categorize each restaurant based on its name and any available description.
    A restaurant can belong to multiple categories.
    Consider both the dining style (Fine Dining, Casual) and cuisine type.
    Examples:
    - A high-end Italian restaurant would be both "Fine Dining" and "Italian"
    - A casual American pub would be both "Casual Dining" and "American"
    """,
    categories=categories,
    allow_multiple=True,
    inputs=unique_restaurants
)

Visualize​

Example:
viz_result = executor.visualize(
    instructions="""
    Create an interactive bar chart showing the distribution of restaurant categories.
    Requirements:
    - Use a horizontal bar chart for better readability of category names
    - Sort bars by count in descending order
    - Use a pleasant color scheme (preferably blues or teals)
    - Include hover tooltips showing exact count
    - Add a clear title 'Restaurant Categories Distribution'
    - Make the chart responsive to container width
    - Include total number of restaurants in each category
    """,
    data=viz_data
)
Think of this as a toolbox

Each primitive is a specialized tool designed to perform a specific task on your data. They're flexible, composable, and context-aware, letting you build intelligent workflows by combining natural language instructions with structured input.

As you add your own custom business logic, you're providing more specific tools to PromptQL.

Execute Program Endpoint​

Execute a PromptQL program with your data.

POST https://promptql.ddn.hasura.app/api/execute_program

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>/api/execute_program

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

API Versions​

The Execute Program API supports two versions:

  • Version 1 (v1): Uses direct DDN URL configuration with optional LLM settings
  • Version 2 (v2): Uses DDN build-based configuration with settings from build metadata

Request Specifications​

Request​

Headers​

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

Version 1 requests support both the Authorization header (recommended) and the deprecated promptql_api_key field in the request body. For new implementations, use the Authorization header with the Bearer <your-promptql-api-key> token format.

Request Body​

{
  "version": "v1",
  "code": "<YOUR_PROMPTQL_GENERATED_CODE_HERE>",
  "promptql_api_key": "<YOUR_API_KEY_HERE>",
  "ai_primitives_llm": {
    "provider": "hasura"
  },
  "ddn": {
    "url": "https://<PROJECT_NAME>.ddn.hasura.app/v1/sql",
    "headers": {}
  },
  "artifacts": []
}

Request Body Fields​

FieldTypeRequiredDescription
versionstringNoOptional, must be "v1" for version 1 requests
codestringYesThe PromptQL program code to execute
promptql_api_keystringNo*PromptQL API key (deprecated, use Authorization header)
ai_primitives_llmobjectYesConfiguration for the AI primitives LLM provider
ddnobjectYesDDN configuration including URL and headers
artifactsarrayYesList of artifacts to provide as context or initial state

*Required if not using Authorization header

LLM Provider Options​

The ai_primitives_llm field supports the following providers:

  1. Hasura:
{
  "provider": "hasura"
}
  1. Anthropic:
{
  "provider": "anthropic",
  "api_key": "<your anthropic api key>"
}
  1. OpenAI:
{
  "provider": "openai",
  "api_key": "<your openai api key>"
}

Artifacts​

The artifacts array can contain both text and table artifacts:

  1. Text Artifact:
{
  "identifier": "my_text",
  "title": "My Text Document",
  "artifact_type": "text",
  "data": "Text content here"
}
  1. Table Artifact:
{
  "identifier": "my_table",
  "title": "My Data Table",
  "artifact_type": "table",
  "data": [
    {
      "column1": "value1",
      "column2": "value2"
    }
  ]
}

Request DDN Auth​

The ddn.headers field can be used to pass any auth header information through to DDN. Read more about auth with these APIs.

Response​

{
  "output": "<program output>",
  "error": null,
  "accessed_artifact_ids": ["artifact1", "artifact2"],
  "modified_artifacts": [
    {
      "identifier": "new_artifact",
      "title": "New Artifact",
      "artifact_type": "table",
      "data": [
        {
          "column1": "value1",
          "column2": "value2"
        }
      ]
    }
  ],
  "llm_usages": [
    {
      "provider": "anthropic",
      "model": "claude-3-5-sonnet-20241022",
      "input_tokens": 691,
      "output_tokens": 33
    }
  ]
}

Response Fields​

FieldTypeDescription
outputstringThe program's output, similar to what you see in the playground
errorstring|nullError message if execution failed, null otherwise
accessed_artifact_idsarrayList of artifact identifiers that were accessed during execution
modified_artifactsarrayList of artifacts that were created or modified during execution
llm_usagesarrayDetails about LLM usage during execution

LLM Usage Fields​

FieldTypeDescription
providerstringThe LLM provider used (e.g., "hasura", "anthropic", "openai")
modelstringThe specific model used
input_tokensintegerNumber of input tokens consumed
output_tokensintegerNumber of output tokens generated

Error Response​

When the API encounters an error, it will return a 422 status code with a validation error response:

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

DDN Authentication​

Both API versions support passing authentication headers to DDN through the ddn.headers field.

Configure headers in the ddn.headers object:

{
  "code": "<YOUR_PROMPTQL_GENERATED_CODE_HERE>",
  "ddn": {
    "url": "https://<PROJECT_NAME>.ddn.hasura.app/v1/sql",
    "headers": {
      "x-hasura-ddn-token": "<YOUR_DDN_AUTH_TOKEN>"
    }
  }
}

Read more about auth with these APIs.

Notes for using the Execute Program API​

  1. Program Code

    • Ensure your PromptQL program code is properly formatted and tested
    • You can export working programs from the PromptQL playground using the "Export as API" button

  2. Build Selection (Version 2)

    • When using v2, you can specify either build_id or build_version, but not both
    • If neither is specified, the project's applied build is automatically used

  3. Artifacts

    • Provide all necessary artifacts that your program needs to run
    • Make sure artifact identifiers match those referenced in your program code
    • Both text and table artifacts are supported

  4. Error Handling

    • Always check the error field in the response
    • Implement appropriate retry logic for transient failures
    • Validate your inputs against the API schema to catch issues early

Get PromptQL programs from the playground​

You don't have to write these programs yourself! You can get PromptQL programs from Playground interactions by clicking on the "Export as API" button next to the Query Plan. Then, you can use the exported program in the code key-value pair in your request to the /execute_program endpoint.

Export as API