Skip to main content

Native API Integration

Every Genum prompt comes with a ready-to-use HTTP API. You can trigger AI behavior programmatically, using versioned prompts as deterministic, testable logic components.

Authentication​

Genum uses Bearer token authentication. API Keys are managed under:

  • Settings → Project → API Keys

These keys are scoped by project and represent access to specific prompt environments and integrations. Create API Key

API Methods​

Endpoint

POST https://api.genum.ai/api/v1/prompts/run

Headers

{
  "Authorization": "Bearer YOUR_API_KEY"
}

Request Body

{
  "id": "YOUR_PROMPT_ID",               // Required: Prompt ID
  "question": "Your input text here",   // Required: Input to process
  "files": [                            // Optional: up to 3 files, total request max 50MB
    {
      "fileName": "invoice.pdf",
      "contentType": "application/pdf",
      "base64": "JVBERi0xLjQKJ..."      // Base64 content (raw or data URL)
    }
  ],
  "placeholders": {                     // Optional: one value NAME per placeholder key
    "tone": "formal"
  },
  "productive": true                    // Optional: Use committed version (default: true)
}

productive: true ensures that only committed and tested prompts are executed. If the prompt has no committed version yet, the request fails with 404.

placeholders selects, for each placeholder in the prompt, the name of the value to use. A placeholder you do not select uses its default value.

Deprecated: memoryKey

memoryKey is still accepted and is equivalent to "placeholders": { "memory_key": "..." }. If both are sent, placeholders.memory_key wins. See Migrating from Memory.

Response Format

{
  "answer": "Generated response",
  "tokens": {
    "prompt": 10,
    "completion": 20,
    "total": 30
  },
  "response_time_ms": 500,
  "chainOfThoughts": "Optional reasoning chain",
  "status": "Optional status (e.g. NOK: error message)",
  "placeholders": {
    "resolved": { "tone": "formal" },   // key -> the value name actually used (null if none)
    "ignored": ["language"]             // keys you sent that were not applied
  }
}

A key is ignored when the prompt text has no {{key}} for it, or when no value has the name you sent. In the second case the default value is used. Check ignored to catch typos early.

Error Handling

{
  "error": "Error message"
}

Errors may result from:

  • ❌ Invalid API key
  • ❌ Missing or incorrect prompt ID
  • ❌ No committed version when productive is true
  • ❌ Exceeded rate limits
  • ❌ Upstream model failure

Instruction Format​

Every prompt has an instructionFormat that controls how its text is prepared before it is sent to the model:

FormatWhat the model receives
XML (default)The prompt converted into structured XML: Markdown headings become XML tags, blank and --- lines are removed, and the result is wrapped in <instructions>.
RAWThe prompt exactly as written, with placeholders filled in and no wrapper.

All existing prompts use XML. Choose RAW when you want Markdown to reach the model as Markdown. The format can currently be set through the API, when creating a prompt.

The Render endpoint always returns the instruction in the prompt's format, so you can see exactly what the model receives.

Why Native API?​

  • Use Genum as a stable runtime layer
  • Integrate with CI/CD workflows
  • Reuse your testable prompts in production scenarios
  • Control prompt execution through placeholders and version flags
  • Render prompts for your own agent loop, identical to what Genum sends
  • Create prompts with their placeholders programmatically
  • Retrieve prompt metadata for integration and monitoring
  • List all prompts for discovery and management

Native API makes your prompts portable, auditable, and production-grade.

Running your own agent? Send its traces back to Genum with OpenTelemetry and turn real conversations into test cases.