Skip to main content
Version: PromptQL

Execute Program API

Introduction​

The Execute Program API is the interface for running PromptQL programs against your connected data. It allows you to trigger atomic, LLM-powered operations through a simple HTTP request—returning structured outputs, modifying artifacts, and recording LLM usage as part of the execution.

This API gives you precise control over program behavior and environment configuration, making it easy to integrate PromptQL workflows into your own systems.

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