Overview

The Dimedove API lets you programmatically create conversations, send messages, and receive AI agent responses. Use it to build custom lead qualification chat applications or embed conversational AI into your own applications.

Base URL

All API requests are made to:

https://api.dimedove.com/v1/apps/{app_id}

Authentication

The API uses Bearer token authentication with your secret API key.

Authorization: Bearer sk_live_your_api_key

You can create and manage API keys from the API Keys page in your dashboard.

Never expose your secret API key (sk_live_*) in client-side code. All API requests should be made from your server.

Error Handling

The API returns errors in an OpenAI-compatible format:

{
  "error": {
    "message": "Human-readable description",
    "type": "error_type",
    "param": null,
    "code": null
  }
}

Error Types

Type	Status	Description
`invalid_api_key`	401	Invalid or missing API key
`access_denied`	403	API key does not have access to this app
`app_inactive`	403	App is disabled
`agent_unavailable`	403	No active agent configured for this app
`not_found`	404	App or conversation not found
`rate_limit_exceeded`	429	Rate limit exceeded
`internal_error`	500	Unexpected server error

Rate Limits

The API applies rate limits based on your plan. Limits are enforced per minute and per day. For more information, contact us.

Pagination

List endpoints use cursor-based pagination with the following query parameters:

Parameter	Type	Default	Description
`limit`	integer	20	Number of results to return (1-100)
`after`	string	-	Cursor for forward pagination (conversation ID)
`before`	string	-	Cursor for backward pagination (conversation ID)
`order`	string	`desc`	Sort order: `asc` or `desc`

Paginated responses include:

{
  "object": "list",
  "data": [...],
  "first_id": "first-conversation-id",
  "last_id": "last-conversation-id",
  "has_more": true
}

Use last_id as the after parameter to fetch the next page.

Streaming

The Send Message endpoint supports Server-Sent Events (SSE) for streaming responses. Set stream: true in the request body to enable streaming. Streaming responses use the text/event-stream content type with the following event format:

event: <event_type>
data: <json_payload>

Event Types

Event	Description
`response.created`	Initial event with response metadata
`response.output_text.delta`	Incremental text chunk from the agent
`response.output_text.done`	Complete assembled text
`response.function_call.start`	Agent initiated a tool call
`response.function_call_arguments.delta`	Incremental tool call arguments
`response.function_call_arguments.done`	Complete tool call arguments
`response.data_spec`	Generative UI form patch (only when Generative UI is enabled)
`response.completed`	Response finished successfully
`response.failed`	Response encountered an error

Streaming Example

event: response.created
data: {"id":"resp_abc123","object":"response","status":"in_progress","conversation_id":"550e8400-e29b-41d4-a716-446655440000"}

event: response.output_text.delta
data: {"type":"response.output_text.delta","delta":"Hello","output_index":0,"content_index":0}

event: response.output_text.delta
data: {"type":"response.output_text.delta","delta":"! How can I help?","output_index":0,"content_index":0}

event: response.output_text.done
data: {"type":"response.output_text.done","text":"Hello! How can I help?","output_index":0,"content_index":0}

event: response.completed
data: {"id":"resp_abc123","status":"completed"}

Generative UI

When Generative UI is enabled on your app, the agent can generate interactive forms (radio buttons, selects, text inputs, and more) to collect structured user input during conversations. These forms are streamed as response.data_spec events containing JSON Patch (RFC 6902) operations that describe the UI components to render. You can enable Generative UI from your app’s configuration page in the dashboard. Each response.data_spec event contains a JSON Patch operation describing a UI component:

{
  "type": "response.data_spec",
  "data": {
    "type": "patch",
    "patch": {
      "op": "add",
      "path": "/root",
      "value": "card-coverage"
    }
  },
  "output_index": 0
}

The data.patch field follows the RFC 6902 JSON Patch specification. Multiple response.data_spec events may be emitted during a single response to progressively build up a form. When Generative UI is enabled, response.data_spec events are interleaved with text events:

event: response.created
data: {"id":"resp_def456","object":"response","status":"in_progress","conversation_id":"550e8400-e29b-41d4-a716-446655440000"}

event: response.output_text.delta
data: {"type":"response.output_text.delta","delta":"Let me help you choose a plan.","output_index":0,"content_index":0}

event: response.output_text.done
data: {"type":"response.output_text.done","text":"Let me help you choose a plan.","output_index":0,"content_index":0}

event: response.data_spec
data: {"type":"response.data_spec","data":{"type":"patch","patch":{"op":"add","path":"/root","value":"card-plan-selection"}},"output_index":0}

event: response.data_spec
data: {"type":"response.data_spec","data":{"type":"patch","patch":{"op":"add","path":"/root/children/-","value":{"type":"radio-group","name":"plan","options":["Basic","Standard","Premium"]}}},"output_index":0}

event: response.completed
data: {"id":"resp_def456","status":"completed"}

Generative UI payloads use JSON Patch operations to describe UI components. Your frontend is responsible for rendering these patches into interactive form elements. You can use the json-render library to render these components in React applications.

Non-Streaming

When streaming is disabled (stream: false or omitted), the Send Message endpoint returns a single JSON response after the agent finishes processing. The response contains an output array with all items produced by the agent. Output items can be of the following types:

Type	Description
`message`	A text message from the assistant
`function_call`	A tool call made by the agent
`data_spec`	A Generative UI form patch (only when Generative UI is enabled)

Non-Streaming Example

{
  "id": "resp_abc123",
  "object": "response",
  "created_at": 1709712000,
  "conversation_id": "550e8400-e29b-41d4-a716-446655440000",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [{ "type": "text", "text": "Hello! How can I help?" }]
    },
    {
      "type": "function_call",
      "name": "lookup_policy",
      "arguments": "{\"query\":\"coverage details\"}",
      "call_id": "call_abc123"
    }
  ],
  "status": "completed"
}

When Generative UI is enabled, data_spec items appear alongside message and function_call items in the output array:

{
  "id": "resp_def456",
  "object": "response",
  "created_at": 1709712000,
  "conversation_id": "550e8400-e29b-41d4-a716-446655440000",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [{ "type": "text", "text": "Let me help you choose a plan." }]
    },
    {
      "type": "data_spec",
      "data": {
        "type": "patch",
        "patch": { "op": "add", "path": "/root", "value": "card-plan-selection" }
      }
    }
  ],
  "status": "completed"
}

Completions

The Create Completion endpoint (POST /apps/{app_id}/completions) generates a single piece of text from a prompt, without creating or belonging to a conversation. Use it for one-shot generation tasks such as autocompleting a form field, drafting a message, or summarizing content, where you want the output written in your agent’s voice and grounded in its business context. Unlike the conversation endpoints, completions:

Do not create a conversation and keep no history (each request is independent)
Use knowledge-base search as their only tool (no other agent tools or tasks run)
Are billed in Work Credits based on token usage, shown in your dashboard under Usage

Send a prompt and receive the generated text:

curl https://api.dimedove.com/v1/apps/{app_id}/completions \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "Write a friendly one-sentence welcome message for a new customer."}'

{
  "id": "cmpl_a1b2c3d4e5f6a7b8c9d0e1f2",
  "object": "completion",
  "created_at": 1709712000,
  "text": "Welcome aboard! We're thrilled to have you and are here to help whenever you need us.",
  "status": "completed"
}

Optional parameters let you tune each request:

Parameter	Type	Default	Description
`stream`	boolean	`false`	Stream the completion as Server-Sent Events (see below)
`knowledge_search`	boolean	`true`	Allow the agent to search its knowledge base to ground the completion
`fast`	boolean	`false`	Skip the model’s internal reasoning step for the lowest latency
`metadata`	object	-	Key-value context to inform the completion (maximum 16KB)

Streaming Completions

Set stream: true to receive the completion as Server-Sent Events. Completions emit only text events, ending with a response.completed event:

event: response.created
data: {"id":"cmpl_abc123","object":"completion","status":"in_progress"}

event: response.output_text.delta
data: {"type":"response.output_text.delta","delta":"Welcome","output_index":0,"content_index":0}

event: response.output_text.done
data: {"type":"response.output_text.done","text":"Welcome aboard!","output_index":0,"content_index":0}

event: response.completed
data: {"id":"cmpl_abc123","status":"completed"}

Getting Started

API Reference

Base URL

Authentication

Error Handling

Error Types

Rate Limits

Streaming

Event Types

Streaming Example

Generative UI

Non-Streaming

Non-Streaming Example

Completions

Streaming Completions

​Base URL

​Authentication

​Error Handling

​Error Types

​Rate Limits

​Pagination

​Streaming

​Event Types

​Streaming Example

​Generative UI

​Non-Streaming

​Non-Streaming Example

​Completions

​Streaming Completions

Base URL

Authentication

Error Handling

Error Types

Rate Limits

Pagination

Streaming

Event Types

Streaming Example

Generative UI

Non-Streaming

Non-Streaming Example

Completions

Streaming Completions