Skip to main content
Version: PromptQL

Natural Language API

Introduction​

The Natural Language Query API allows you to interact with PromptQL directly, sending messages and receiving responses with support for streaming. This API is particularly useful for building interactive applications that need to communicate with PromptQL in real-time.

Example request using our quickstart:
{
  "version": "v1",
  "promptql_api_key": "<YOUR_API_KEY_HERE>",
  "llm": {
    "provider": "hasura"
  },
  "ddn": {
    "url": "https://<PROJECT_NAME>.ddn.hasura.app/v1/sql",
    "headers": {}
  },
  "artifacts": [],
  "system_instructions": "Responde solo en espanol, por favor",
  "timezone": "America/Los_Angeles",
  "interactions": [
    {
      "user_message": {
        "text": "What can you do?"
      },
      "assistant_actions": []
    }
  ],
  "stream": false
}

Click here to see a sample response ☝️

Example response using our quickstart:
{
  "assistant_actions": [
    {
      "message": "¡Hola! Soy un asistente que puede ayudarte con varias tareas relacionadas con películas. Específicamente, puedo:\n\n1. Buscar y analizar películas de la base de datos basado en diferentes criterios como:\n   - Título\n   - Director\n   - Año de lanzamiento\n   - Género\n   - Calificación IMDB\n   - Actores\n   - Y más\n\n2. Ayudarte a rentar películas a través del servicio Promptflix\n\n3. Crear análisis y resúmenes personalizados de películas\n\n4. Responder preguntas sobre películas específicas o tendencias generales\n\n¿Hay algo específico sobre películas que te gustaría explorar?",
      "plan": null,
      "code": null,
      "code_output": null,
      "code_error": null
    }
  ],
  "modified_artifacts": []
}

Query Endpoint​

Send messages to PromptQL and receive responses, optionally in a streaming format.

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

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/query

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

API Versions​

The Natural Language 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",
  "promptql_api_key": "<YOUR_API_KEY_HERE>",
  "llm": {
    "provider": "hasura"
  },
  "ddn": {
    "url": "https://<PROJECT_NAME>.ddn.hasura.app/v1/sql",
    "headers": {}
  },
  "artifacts": [],
  "system_instructions": "Optional system instructions for the LLM",
  "timezone": "America/Los_Angeles",
  "interactions": [
    {
      "user_message": {
        "text": "Your message here"
      },
      "assistant_actions": [
        {
          "message": "Previous assistant message",
          "plan": "Previous execution plan",
          "code": "Previously executed code",
          "code_output": "Previous code output",
          "code_error": "Previous error message if any"
        }
      ]
    }
  ],
  "stream": false
}

Request Body Fields​

FieldTypeRequiredDescription
versionstringYesMust be set to "v1"
promptql_api_keystringYesPromptQL API key created from project settings
llmobjectNoConfiguration for the main LLM provider
ai_primitives_llmobjectNoOptional Configuration for the AI primitives LLM provider. If this is missing, the main LLM provider is used
ddnobjectYesDDN configuration including URL and headers
artifactsarrayNoList of existing artifacts to provide context
system_instructionsstringNoCustom system instructions for the LLM
timezonestringYesIANA timezone for interpreting time-based queries
interactionsarrayYesList of message interactions, including user messages and assistant responses. Each interaction contains a user_message object with the user's text and an optional assistant_actions array containing previous assistant responses with their messages, plans, code executions, and outputs.
streambooleanYesWhether to return a streaming response

LLM Provider Configuration​

The llm and ai_primitives_llm fields support the following providers:

  1. Hasura:
{
  "provider": "hasura"
}
Free credits

You get $20 worth of free credits with Hasura's built-in provider during the trial. Reach out to us to add more credits.

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

Authentication​

PromptQL API Authentication​

Both API versions require authentication using your PromptQL API key:

  • Version 1: Supports both Authorization header (recommended) and deprecated promptql_api_key field
  • Version 2: Requires Authorization header with Bearer token format

DDN Authentication​

The ddn.headers field allows you to pass authentication headers to your DDN endpoint and is supported in both version 1 (v1) and version 2 (v2) requests. This enables you to use any DDN-compatible authentication strategy with the Natural Language API.

Configure headers in the ddn.headers object:

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

The headers you need to include depend on your DDN project's authentication configuration. For comprehensive information about setting up authentication modes and understanding which headers to use, refer to our Authentication in APIs documentation.

Response Format​

The response format depends on the stream parameter in your request:

Non-streaming Response​

Content-Type: application/json

{
  "assistant_actions": [
    {
      "message": "Response message",
      "plan": "Execution plan",
      "code": "Executed code",
      "code_output": "Code output",
      "code_error": "Error message if any"
    }
  ],
  "modified_artifacts": [
    {
      "identifier": "artifact_id",
      "title": "Artifact Title",
      "artifact_type": "text|table",
      "data": "artifact_data"
    }
  ]
}

Streaming Response​

Content-Type: text/event-stream

The streaming response sends chunks of data in Server-Sent Events (SSE) format:

data: {
  "message": "Chunk of response message",
  "plan": null,
  "code": null,
  "code_output": null,
  "code_error": null,
  "type": "assistant_action_chunk",
  "index": 0
}

data: {
  "type": "artifact_update_chunk",
  "artifact": {
    "identifier": "artifact_id",
    "title": "Artifact Title",
    "artifact_type": "text|table",
    "data": "artifact_data"
  }
}

Response Fields​

FieldTypeDescription
assistant_actionsarrayList of actions taken by the assistant
modified_artifactsarrayList of artifacts created or modified during the interaction

Assistant Action Fields

FieldTypeDescription
messagestringText response from the assistant
planstringExecution plan if any
codestringCode that was executed
code_outputstringOutput from code execution
code_errorstringError message if code execution failed

Error Response​

{
  "type": "error_chunk",
  "error": "Error message describing what went wrong"
}

Notes for using the Natural Language API​

  1. Streaming vs Non-streaming

    • Use streaming (stream: true) for real-time interactive applications
    • Use non-streaming (stream: false) for batch processing or when you need the complete response at once

  2. Artifacts

    • You can pass existing artifacts to provide context for the conversation
    • Both text and table artifacts are supported
    • Artifacts can be modified or created during the interaction

  3. Timezone Handling

    • Always provide a timezone to ensure consistent handling of time-based queries
    • Use standard IANA timezone formats (e.g., "America/Los_Angeles", "Europe/London")

  4. Error Handling

    • Always check for error responses, especially in streaming mode
    • Implement appropriate retry logic for transient failures