ask-ava-sync

dci ask-ava-sync [body]

Send a question to Ava and receive a synchronous response. Set ephemeral to true to skip conversation persistence (recommended for programmatic consumers). When ephemeral is false (default), the response includes a conversationId that can be used with the delete endpoint.

Pass the request body as name: value arguments or pipe JSON on stdin — see Command structure.

Ephemeral or persisted

ephemeral: true skips conversation persistence — the recommended mode for programmatic use. With the default ephemeral: false, the response includes a conversationId (continue with another question, or clean up with dci delete-ava-conversation) and an answerId (needed by dci submit-ava-feedback).

Errors can arrive with HTTP 200

If generation fails after the response has begun, the body carries an error field instead of answer while the status stays 200 — check for answer before using the result.

Examples

# A one-shot question that leaves no conversation behind (recommended for scripts and agents).
dci ask-ava-sync ephemeral: true, question: "Why did costs spike yesterday?"

# Start a persisted conversation; the response carries a conversationId and answerId.
dci ask-ava-sync question: "What are my top cost drivers this month?" --output json

# Continue that conversation.
dci ask-ava-sync question: "Break down EC2 by region", conversationId: <conversation-id>

# Just the answer text, for a pipeline.
dci ask-ava-sync ephemeral: true, question: "Which service grew the most this month?" --output json | jq -r .answer

Request

Content-Type: application/json

Field	Type	Required	Description
question	string	yes	The question to ask Ava.
conversationId	string		Optional ID of an existing conversation to continue.
ephemeral	boolean		When true, the conversation is not persisted. Recommended for programmatic consumers (Terraform, MCP, CI pipelines). Default: false.

Raw JSON schema

{
  "type": "object",
  "properties": {
    "question": {
      "type": "string",
      "description": "The question to ask Ava."
    },
    "conversationId": {
      "type": "string",
      "description": "Optional ID of an existing conversation to continue."
    },
    "ephemeral": {
      "type": "boolean",
      "default": false,
      "description": "When true, the conversation is not persisted. Recommended for programmatic consumers (Terraform, MCP, CI pipelines)."
    }
  },
  "required": [
    "question"
  ]
}

Output

OK - Ava response returned.

By default dci renders the result as a table. Use --output json to get the full structure described below — see Output formats.

Field	Type	Description
answer	string	The Ava response text. Present on success.
conversationId	string	The conversation ID. Present only for non-ephemeral requests. Can be used with the delete conversation endpoint.
answerId	string	The answer ID within the conversation. Present only for non-ephemeral requests. Required for the feedback endpoint.
error	string	Present instead of answer when generation fails after the response has begun streaming (the HTTP status remains 200). A human-readable error message.

Raw JSON schema

{
  "type": "object",
  "description": "Ava's response. On success, `answer` is present. The endpoint streams keep-alive whitespace while generating (to avoid proxy timeouts), so the HTTP status is committed to 200 before the answer is ready; if generation then fails, `answer` is omitted and `error` carries a message instead. Consumers should check for `error` before reading `answer`.",
  "properties": {
    "answer": {
      "type": "string",
      "description": "The Ava response text. Present on success."
    },
    "conversationId": {
      "type": "string",
      "description": "The conversation ID. Present only for non-ephemeral requests. Can be used with the delete conversation endpoint."
    },
    "answerId": {
      "type": "string",
      "description": "The answer ID within the conversation. Present only for non-ephemeral requests. Required for the feedback endpoint."
    },
    "error": {
      "type": "string",
      "description": "Present instead of `answer` when generation fails after the response has begun streaming (the HTTP status remains 200). A human-readable error message."
    }
  }
}

Errors

On failure, dci prints a single error message — with a hint when one is available — and exits with a typed code your scripts can branch on. See Errors and exit codes for the full contract.

HTTP status to exit code mapping

HTTP status	Exit code	Error code	Meaning
400	30	VALIDATION_ERROR	The arguments or request body were rejected. Review the command's flags and payload.
401	10	AUTHENTICATION_FAILED	Not signed in, or the API token is invalid. Run dci login or check DCI_API_KEY.
403	11	PERMISSION_DENIED	The DoiT user or the active customer context does not have access.
500	40	API_SERVER_ERROR	The API failed to process the request. Retryable; contact DoiT support if it persists.

Related

• ask-ava-streaming — Ask Ava (streaming)
• delete-ava-conversation — Delete a conversation
• submit-ava-feedback — Submit feedback
• API reference: POST /ava/v1/askSync

Aliases: askavasync