# Create ask request

URL: /en/docs/api/v1/ask/post
Last Updated: 2026-07-30T21:15:44.916Z

## Description
No description available.

## Available Actions
- Execute POST request
- View request parameters
- View response schema
- Get code examples
- Navigate to related topics
- View step-by-step instructions
- Get best practices

## Content
### POST /api/v1/ask

**Create ask request**

Submit a question for AI-assisted answer generation.

The endpoint creates a persisted ask record and queues a background generation job.
If the job reaches a terminal state quickly, a terminal response is returned with HTTP 200.
Otherwise, an in-progress response is returned with HTTP 202.

**Authentication:** Bearer token (`Authorization: Bearer <token>`)

**Request body** (`application/json`) - required:

Example (Free-text question):

```json
{
  "question": "Do you have a SOC 2 report available?",
  "question_type": "text"
}
```

Example (Select question with options):

```json
{
  "question": "What is your primary cloud provider?",
  "question_type": "select",
  "question_options": [
    "AWS",
    "Google Cloud",
    "Azure"
  ]
}
```

**Responses:**

- `200` - Ask response is available in a terminal state
  - `id` (string, required): Ask response identifier.
  - `object` (enum: response, required): Object type.
  - `status` (enum: in_progress | completed | failed | incomplete, required): Current status of the ask response.
  - `created_at` (integer, required): Unix timestamp (seconds) when the ask response was created.
  - `output` (array of AskOutputMessage (object)): Assistant output messages (present when completed with output).
    - `type` (enum: message, required)
    - `id` (string, required)
    - `role` (enum: assistant, required)
    - `status` (enum: completed, required)
    - `content` (array of AskOutputText (object), required)
      - `type` (enum: output_text, required)
      - `text` (string, required)
  - `usage` (AskUsage (object))
    - `input_tokens` (integer, required)
    - `output_tokens` (integer, required)
    - `total_tokens` (integer)
  - `error` (AskError (object))
    - `type` (string, required)
    - `code` (string, required)
    - `message` (string, required)

  Example (Completed response):
  
  ```json
  {
  "id": "ask_1",
  "object": "response",
  "status": "completed",
  "created_at": 1771920000,
  "output": [
    {
      "type": "message",
      "id": "msg_ask1",
      "role": "assistant",
      "status": "completed",
      "content": [
        {
          "type": "output_text",
          "text": "Yes, a SOC 2 report is available under NDA."
        }
      ]
    }
  ],
  "usage": {
    "input_tokens": 125,
    "output_tokens": 42,
    "total_tokens": 167
  }
}
  ```

  Example (Failed response):
  
  ```json
  {
  "id": "ask_2",
  "object": "response",
  "status": "failed",
  "created_at": 1771920000,
  "error": {
    "type": "model_error",
    "code": "generation_failed",
    "message": "Failed to generate response"
  }
}
  ```
- `202` - Ask request accepted and still processing
  - `id` (string, required): Ask response identifier.
  - `object` (enum: response, required): Object type.
  - `status` (enum: in_progress | completed | failed | incomplete, required): Current status of the ask response.
  - `created_at` (integer, required): Unix timestamp (seconds) when the ask response was created.
  - `output` (array of AskOutputMessage (object)): Assistant output messages (present when completed with output).
    - `type` (enum: message, required)
    - `id` (string, required)
    - `role` (enum: assistant, required)
    - `status` (enum: completed, required)
    - `content` (array of AskOutputText (object), required)
      - `type` (enum: output_text, required)
      - `text` (string, required)
  - `usage` (AskUsage (object))
    - `input_tokens` (integer, required)
    - `output_tokens` (integer, required)
    - `total_tokens` (integer)
  - `error` (AskError (object))
    - `type` (string, required)
    - `code` (string, required)
    - `message` (string, required)

  Example (In-progress response):
  
  ```json
  {
  "id": "ask_1",
  "object": "response",
  "status": "in_progress",
  "created_at": 1771920000
}
  ```
- `400` - Invalid JSON payload or invalid input
  - `error` (string)
  - `error` (string)
  - `details` (object)

  Example (Invalid JSON body):
  
  ```json
  {
  "error": "Invalid JSON"
}
  ```

  Example (Validation failed):
  
  ```json
  {
  "error": "Invalid input",
  "details": {
    "errors": [
      {
        "path": [
          "question_options"
        ],
        "message": "question_options are required for select and multi_select"
      }
    ]
  }
}
  ```
- `401` - Unauthorized
  - `error` (string)

  Example (unauthorized):
  
  ```json
  {
  "error": "Unauthorized"
}
  ```

  Example (token_expired):
  
  ```json
  {
  "error": "Token expired"
}
  ```
- `502` - Failed to queue ask request
  - `error` (string)

**Code samples:**

cURL (text question):

```bash
curl -X POST "https://app.orbiqhq.com/api/v1/ask" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "Do you have a SOC 2 report available?",
    "question_type": "text"
  }'

```

cURL (select question):

```bash
curl -X POST "https://app.orbiqhq.com/api/v1/ask" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "What is your primary cloud provider?",
    "question_type": "select",
    "question_options": ["AWS", "Google Cloud", "Azure"]
  }'

```