> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dimedove.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create completion

> Generates a one-shot text completion using the app's agent configuration. Unlike the conversation endpoints, this does not create or belong to a conversation. It produces a single piece of text from your instruction, grounded in the agent's business context. Supports both streaming (Server-Sent Events) and non-streaming (JSON) modes.



## OpenAPI

````yaml /openapi/apps-api.json post /apps/{app_id}/completions
openapi: 3.1.0
info:
  title: Dimedove API
  version: 1.0.0
  description: >-
    Programmatically manage conversations and interact with your AI agents
    through the Dimedove API.
servers:
  - url: https://api.dimedove.com/v1
    description: Production
security: []
paths:
  /apps/{app_id}/completions:
    post:
      tags:
        - Completions
      summary: Create completion
      description: >-
        Generates a one-shot text completion using the app's agent
        configuration. Unlike the conversation endpoints, this does not create
        or belong to a conversation. It produces a single piece of text from
        your instruction, grounded in the agent's business context. Supports
        both streaming (Server-Sent Events) and non-streaming (JSON) modes.
      operationId: apps_api_create_completion
      parameters:
        - in: path
          name: app_id
          schema:
            description: The unique identifier of the app.
            title: App Id
            type: string
          required: true
          description: The unique identifier of the app.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CompletionRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CompletionResponseSchema'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenAIErrorSchema'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenAIErrorSchema'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenAIErrorSchema'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OpenAIErrorSchema'
      security:
        - AppsApiKeyAuth: []
components:
  schemas:
    CompletionRequest:
      example:
        fast: false
        knowledge_search: true
        metadata:
          first_name: Alex
          page: pricing
        prompt: Write a friendly one-sentence welcome message for a new customer.
        stream: false
      properties:
        prompt:
          description: >-
            The instruction describing the text to generate. The completion is
            produced in your app's agent voice, grounded in its configured
            business context. Treated strictly as a generation instruction, not
            as a command that can change the agent's behavior. Maximum 32,000
            characters.
          minLength: 1
          title: Prompt
          type: string
        stream:
          anyOf:
            - type: boolean
            - type: 'null'
          description: >-
            When true, the completion is delivered as Server-Sent Events (SSE).
            When false or omitted, a single JSON response is returned.
          title: Stream
        knowledge_search:
          default: true
          description: >-
            Whether the agent may search its knowledge base to ground the
            completion. Set to false for lower latency when the completion does
            not need business-specific facts. Has no effect if the agent has no
            knowledge base configured.
          title: Knowledge Search
          type: boolean
        fast:
          default: false
          description: >-
            When true, the model skips its internal reasoning step for the
            lowest latency. When false, the model does light planning before
            generating, which can improve quality on complex instructions.
          title: Fast
          type: boolean
        metadata:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          description: >-
            Arbitrary key-value context to inform the completion (for example
            the form field being completed, or details about the user). Injected
            into the agent's runtime context as data, never as instructions.
            Maximum 16KB.
          title: Metadata
      required:
        - prompt
      title: CompletionRequest
      type: object
    CompletionResponseSchema:
      example:
        created_at: 1717027200
        id: cmpl_a1b2c3d4e5f6a7b8c9d0e1f2
        object: completion
        status: completed
        text: >-
          Welcome aboard, Alex. We're thrilled to have you and are here to help
          whenever you need us.
      properties:
        id:
          description: Unique identifier for the completion, prefixed with 'cmpl_'.
          title: Id
          type: string
        object:
          default: completion
          description: The object type. Always 'completion'.
          title: Object
          type: string
        created_at:
          description: Unix timestamp (in seconds) of when the completion was generated.
          title: Created At
          type: integer
        text:
          description: The generated completion text.
          title: Text
          type: string
        status:
          default: completed
          description: The status of the completion. Either 'completed' or 'failed'.
          title: Status
          type: string
      required:
        - id
        - created_at
        - text
      title: CompletionResponseSchema
      type: object
    OpenAIErrorSchema:
      properties:
        error:
          $ref: '#/components/schemas/OpenAIErrorDetail'
          description: The error detail object.
      required:
        - error
      title: OpenAIErrorSchema
      type: object
    OpenAIErrorDetail:
      properties:
        message:
          description: A human-readable description of the error.
          title: Message
          type: string
        type:
          description: >-
            The error type identifier (e.g. 'invalid_api_key', 'not_found',
            'rate_limit_exceeded').
          title: Type
          type: string
        param:
          anyOf:
            - type: string
            - type: 'null'
          description: The parameter that caused the error, if applicable.
          title: Param
        code:
          anyOf:
            - type: string
            - type: 'null'
          description: An error code providing additional detail, if applicable.
          title: Code
      required:
        - message
        - type
      title: OpenAIErrorDetail
      type: object
  securitySchemes:
    AppsApiKeyAuth:
      type: http
      scheme: bearer

````