> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://help.moveworks.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://help.moveworks.com/_mcp/server.

# Create response

POST https://api.moveworks.ai/assistant/v1/conversations/{conversation_id}/responses
Content-Type: application/json

Creates a response object for processing. Returns immediately with the response object. Use `GetResponse` by `response_id` to poll for the complete result.

Reference: https://help.moveworks.com/api-reference/conversations-api/responses/create-response

## OpenAPI Specification

```yaml
openapi: 3.1.0
info:
  title: conversations-api-v1
  version: 1.0.0
paths:
  /conversations/{conversation_id}/responses:
    post:
      operationId: create-response
      summary: Create response
      description: >-
        Creates a response object for processing. Returns immediately with the
        response object. Use `GetResponse` by `response_id` to poll for the
        complete result.
      tags:
        - responses
      parameters:
        - name: conversation_id
          in: path
          description: A base-62 identifier prefixed by a short resource type
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: >-
            JWT bearer token authentication. Obtain an access token from the
            Moveworks auth endpoint and include it in the Authorization header
            as 'Bearer <token>'.
          required: true
          schema:
            type: string
        - name: Assistant-Name
          in: header
          description: >-
            The Moveworks assistant identifier that was configured for your
            organization.
          required: true
          schema:
            type: string
      responses:
        '202':
          description: Response accepted for processing (acknowledgement)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
        '400':
          description: Bad request - Invalid input parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InputRequiredErrorResponse'
        '401':
          description: Unauthorized - Invalid or missing authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorResponse'
        '403':
          description: Forbidden - Invalid assistant
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenErrorResponse'
        '404':
          description: Not found - Resource does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrorResponse'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitExceededErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalErrorResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateResponseRequest'
servers:
  - url: https://api.moveworks.ai/assistant/v1
    description: US production server
components:
  schemas:
    UserInput0:
      type: object
      properties:
        text:
          type: string
          description: User message text
      required:
        - text
      title: UserInput0
    UserInput1:
      type: object
      properties:
        callback_id:
          type: string
          description: >-
            Opaque callback id for an action the user triggered (e.g. clicking a
            button rendered in a prior assistant message).
      required:
        - callback_id
      title: UserInput1
    UserInput:
      oneOf:
        - $ref: '#/components/schemas/UserInput0'
        - $ref: '#/components/schemas/UserInput1'
      description: >-
        User input for a response. Exactly one of `text` or `callback_id` must
        be provided.
      title: UserInput
    CreateResponseRequest:
      type: object
      properties:
        input:
          $ref: '#/components/schemas/UserInput'
          description: User input message
      required:
        - input
      title: CreateResponseRequest
    ResponseStatus:
      type: string
      enum:
        - CREATED
        - IN_PROGRESS
        - COMPLETED
        - FAILED
      description: Response processing status
      title: ResponseStatus
    MessageOutputItemType:
      type: string
      enum:
        - MESSAGE
      description: Output item type discriminator
      title: MessageOutputItemType
    ActorType:
      type: string
      enum:
        - USER
        - ASSISTANT
      description: Message actor type
      title: ActorType
    PlainTextContentItemType:
      type: string
      enum:
        - PLAIN_TEXT
      description: Content type discriminator
      title: PlainTextContentItemType
    PlainTextContent:
      type: object
      properties:
        text:
          type: string
          description: Plain text content
      required:
        - text
      title: PlainTextContent
    CommonmarkTextContentItemType:
      type: string
      enum:
        - COMMONMARK_TEXT
      description: Content type discriminator
      title: CommonmarkTextContentItemType
    CommonmarkTextContent:
      type: object
      properties:
        text:
          type: string
          description: Commonmark-formatted text content
      required:
        - text
      title: CommonmarkTextContent
    MarkdownTextContentItemType:
      type: string
      enum:
        - MARKDOWN_TEXT
      description: Content type discriminator
      title: MarkdownTextContentItemType
    MarkdownTextContent:
      type: object
      properties:
        text:
          type: string
          description: >-
            Raw markdown text content. Used when Minerva's chat response
            `is_commonmark` is not set.
      required:
        - text
      title: MarkdownTextContent
    CallbackActionContentItemType:
      type: string
      enum:
        - CALLBACK_ACTION_CONTENT
      description: Content type discriminator
      title: CallbackActionContentItemType
    CallbackActionContent:
      type: object
      properties:
        callback_id:
          type: string
          description: >-
            Opaque callback id for the action the user triggered. Submit this
            via `input.callback_id` on the create response endpoint to trigger
            the action.
      required:
        - callback_id
      title: CallbackActionContent
    Content:
      oneOf:
        - type: object
          properties:
            type:
              $ref: '#/components/schemas/PlainTextContentItemType'
              description: Content type discriminator
            plain_text:
              $ref: '#/components/schemas/PlainTextContent'
          required:
            - type
            - plain_text
          description: PLAIN_TEXT variant
        - type: object
          properties:
            type:
              $ref: '#/components/schemas/CommonmarkTextContentItemType'
              description: Content type discriminator
            commonmark_text:
              $ref: '#/components/schemas/CommonmarkTextContent'
          required:
            - type
            - commonmark_text
          description: COMMONMARK_TEXT variant
        - type: object
          properties:
            type:
              $ref: '#/components/schemas/MarkdownTextContentItemType'
              description: Content type discriminator
            markdown_text:
              $ref: '#/components/schemas/MarkdownTextContent'
          required:
            - type
            - markdown_text
          description: MARKDOWN_TEXT variant
        - type: object
          properties:
            type:
              $ref: '#/components/schemas/CallbackActionContentItemType'
              description: Content type discriminator
            callback_action:
              $ref: '#/components/schemas/CallbackActionContent'
          required:
            - type
            - callback_action
          description: CALLBACK_ACTION_CONTENT variant
      discriminator:
        propertyName: type
      description: Message content with type discriminator
      title: Content
    Attribute:
      type: object
      properties:
        key:
          type: string
          description: Attribute name
        value:
          type: string
          description: Attribute value
      required:
        - key
        - value
      description: >-
        Key-value pair for citation display metadata. This is an opaque
        structure that contains rendering hints specific to each citation.
        Clients should not make assumptions about the keys or values present, as
        they may vary based on citation type and context.
      title: Attribute
    Display:
      type: object
      properties:
        title:
          $ref: '#/components/schemas/Content'
          description: Primary heading/identifier with type discriminator
        body:
          $ref: '#/components/schemas/Content'
          description: Body/description content with type discriminator
        attributes:
          type: array
          items:
            $ref: '#/components/schemas/Attribute'
          description: >-
            Opaque key-value metadata for citation display. These attributes
            contain implementation-specific rendering hints and should be
            treated as a black-box by clients. The structure and values may vary
            between citations and should not be relied upon for business logic.
      title: Display
    Citation:
      type: object
      properties:
        citation_id:
          type: string
          description: >-
            Unique citation identifier (format: `cite_<base62>`). Use this to
            join with `content_references` on the Message object.
        url:
          type: string
          format: uri
          description: URL to the entity
        display:
          $ref: '#/components/schemas/Display'
      title: Citation
    CitationContentReference:
      type: object
      properties:
        citation_id:
          type: string
          description: >-
            References `Citation.citation_id` to link this position to a
            citation entity.
        offset:
          type: integer
          description: >-
            Zero-based character position in the assistant message where the
            citation appears.
      required:
        - citation_id
        - offset
      title: CitationContentReference
    FeedbackOption:
      type: object
      properties:
        callback_id:
          type: string
          description: >-
            Opaque callback identifier. Pass this value to the feedback endpoint
            to submit this rating.
      required:
        - callback_id
      title: FeedbackOption
    MessageFeedback:
      type: object
      properties:
        helpful:
          $ref: '#/components/schemas/FeedbackOption'
          description: >-
            Positive feedback option. Use this callback_id to rate the response
            as helpful.
        unhelpful:
          $ref: '#/components/schemas/FeedbackOption'
          description: >-
            Negative feedback option. Use this callback_id to rate the response
            as unhelpful.
      description: >-
        Feedback options available on an assistant message. When present, this
        message supports feedback and the callback IDs can be used to submit a
        rating.
      title: MessageFeedback
    CallbackActionItemType:
      type: string
      enum:
        - CALLBACK_ACTION
      description: Action type discriminator
      title: CallbackActionItemType
    CallbackAction:
      type: object
      properties:
        callback_id:
          type: string
          description: >-
            Opaque callback identifier for the action. Submit this via
            `input.callback_id` on the create response endpoint to trigger the
            action.
      required:
        - callback_id
      title: CallbackAction
    UrlActionItemType:
      type: string
      enum:
        - URL_ACTION
      description: Action type discriminator
      title: UrlActionItemType
    URLAction:
      type: object
      properties:
        url:
          type: string
          format: uri
          description: URL to open when the action is triggered.
      required:
        - url
      title: URLAction
    Action:
      oneOf:
        - type: object
          properties:
            type:
              $ref: '#/components/schemas/CallbackActionItemType'
              description: Action type discriminator
            label:
              type: string
              description: Label associated with the action (e.g., button text).
            callback_action:
              $ref: '#/components/schemas/CallbackAction'
          required:
            - type
            - label
            - callback_action
          description: CALLBACK_ACTION variant
        - type: object
          properties:
            type:
              $ref: '#/components/schemas/UrlActionItemType'
              description: Action type discriminator
            label:
              type: string
              description: Label associated with the action (e.g., link text).
            url_action:
              $ref: '#/components/schemas/URLAction'
          required:
            - type
            - label
            - url_action
          description: URL_ACTION variant
      discriminator:
        propertyName: type
      description: >-
        An action a user can take in response to a message. The `type` field
        determines which action payload is present.
      title: Action
    Message:
      type: object
      properties:
        message_id:
          type: string
          description: A base-62 identifier prefixed by a short resource type
        conversation_id:
          type: string
          description: A base-62 identifier prefixed by a short resource type
        response_id:
          type: string
          description: A base-62 identifier prefixed by a short resource type
        actor:
          $ref: '#/components/schemas/ActorType'
        content:
          $ref: '#/components/schemas/Content'
        citations:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/Citation'
          description: >-
            Unique citation references in the assistant message. Use
            `content_references` to determine where in the message text each
            citation is referenced.
        content_references:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/CitationContentReference'
          description: >-
            Ordered positions in the message text where citations appear
            (ascending by offset). Each entry references a `Citation` via
            `citation_id`. Only populated on assistant messages.
        created_at:
          type: string
          format: date-time
          description: Creation timestamp (ISO 8601)
        feedback:
          oneOf:
            - $ref: '#/components/schemas/MessageFeedback'
            - type: 'null'
          description: >-
            Feedback options for this message. Present only on final assistant
            messages that support feedback. Use the callback IDs to submit a
            rating via the feedback endpoint.
        actions:
          type: array
          items:
            $ref: '#/components/schemas/Action'
          description: >-
            Actions a user can take in response to this message (e.g. buttons or
            links). Absent on messages with no actions.
      required:
        - message_id
        - conversation_id
        - response_id
        - actor
        - content
        - created_at
      title: Message
    ReasoningMessageOutputItemType:
      type: string
      enum:
        - REASONING_MESSAGE
      description: Output item type discriminator
      title: ReasoningMessageOutputItemType
    ReasoningMessage:
      type: object
      properties:
        reasoning_message_id:
          type: string
          description: A base-62 identifier prefixed by a short resource type
        conversation_id:
          type: string
          description: A base-62 identifier prefixed by a short resource type
        response_id:
          type: string
          description: A base-62 identifier prefixed by a short resource type
        content:
          $ref: '#/components/schemas/Content'
        created_at:
          type: string
          format: date-time
          description: Creation timestamp (ISO 8601)
      required:
        - reasoning_message_id
        - conversation_id
        - response_id
        - content
        - created_at
      title: ReasoningMessage
    OutputItem:
      oneOf:
        - type: object
          properties:
            type:
              $ref: '#/components/schemas/MessageOutputItemType'
              description: Output item type discriminator
            message:
              $ref: '#/components/schemas/Message'
          required:
            - type
            - message
          description: MESSAGE variant
        - type: object
          properties:
            type:
              $ref: '#/components/schemas/ReasoningMessageOutputItemType'
              description: Output item type discriminator
            reasoning_message:
              $ref: '#/components/schemas/ReasoningMessage'
          required:
            - type
            - reasoning_message
          description: REASONING_MESSAGE variant
      discriminator:
        propertyName: type
      description: Output item wrapper with type discriminator
      title: OutputItem
    Response:
      type: object
      properties:
        response_id:
          type: string
          description: A base-62 identifier prefixed by a short resource type
        conversation_id:
          type: string
          description: A base-62 identifier prefixed by a short resource type
        status:
          $ref: '#/components/schemas/ResponseStatus'
        created_at:
          type: string
          format: date-time
          description: Creation timestamp (ISO 8601)
        completed_at:
          type:
            - string
            - 'null'
          format: date-time
          description: Completion timestamp (ISO 8601), null if not completed
        outputs:
          type: array
          items:
            $ref: '#/components/schemas/OutputItem'
          description: Output items
      required:
        - response_id
        - conversation_id
        - status
        - created_at
      title: Response
    InputRequiredErrorResponseErrorCode:
      type: string
      enum:
        - INVALID_INPUT
      title: InputRequiredErrorResponseErrorCode
    InputRequiredErrorResponseError:
      type: object
      properties:
        code:
          $ref: '#/components/schemas/InputRequiredErrorResponseErrorCode'
        message:
          type: string
      required:
        - code
        - message
      title: InputRequiredErrorResponseError
    InputRequiredErrorResponse:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/InputRequiredErrorResponseError'
      required:
        - error
      description: Error response for missing required input field
      title: InputRequiredErrorResponse
    UnauthorizedErrorResponseErrorCode:
      type: string
      enum:
        - UNAUTHORIZED
      title: UnauthorizedErrorResponseErrorCode
    UnauthorizedErrorResponseError:
      type: object
      properties:
        code:
          $ref: '#/components/schemas/UnauthorizedErrorResponseErrorCode'
        message:
          type: string
      required:
        - code
        - message
      title: UnauthorizedErrorResponseError
    UnauthorizedErrorResponse:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/UnauthorizedErrorResponseError'
      required:
        - error
      description: Error response for unauthorized access
      title: UnauthorizedErrorResponse
    ForbiddenErrorResponseErrorCode:
      type: string
      enum:
        - FORBIDDEN
      title: ForbiddenErrorResponseErrorCode
    ForbiddenErrorResponseError:
      type: object
      properties:
        code:
          $ref: '#/components/schemas/ForbiddenErrorResponseErrorCode'
        message:
          type: string
      required:
        - code
        - message
      title: ForbiddenErrorResponseError
    ForbiddenErrorResponse:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/ForbiddenErrorResponseError'
      required:
        - error
      description: Error response for forbidden access
      title: ForbiddenErrorResponse
    NotFoundErrorResponseErrorCode:
      type: string
      enum:
        - NOT_FOUND
      title: NotFoundErrorResponseErrorCode
    NotFoundErrorResponseError:
      type: object
      properties:
        code:
          $ref: '#/components/schemas/NotFoundErrorResponseErrorCode'
        message:
          type: string
      required:
        - code
        - message
      title: NotFoundErrorResponseError
    NotFoundErrorResponse:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/NotFoundErrorResponseError'
      required:
        - error
      description: Error response for resource not found
      title: NotFoundErrorResponse
    RateLimitExceededErrorResponseErrorCode:
      type: string
      enum:
        - RATE_LIMIT_EXCEEDED
      title: RateLimitExceededErrorResponseErrorCode
    RateLimitExceededErrorResponseError:
      type: object
      properties:
        code:
          $ref: '#/components/schemas/RateLimitExceededErrorResponseErrorCode'
        message:
          type: string
      required:
        - code
        - message
      title: RateLimitExceededErrorResponseError
    RateLimitExceededErrorResponse:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/RateLimitExceededErrorResponseError'
      required:
        - error
      description: Error response for rate limit exceeded
      title: RateLimitExceededErrorResponse
    InternalErrorResponseErrorCode:
      type: string
      enum:
        - INTERNAL_ERROR
      title: InternalErrorResponseErrorCode
    InternalErrorResponseError:
      type: object
      properties:
        code:
          $ref: '#/components/schemas/InternalErrorResponseErrorCode'
        message:
          type: string
      required:
        - code
        - message
      title: InternalErrorResponseError
    InternalErrorResponse:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/InternalErrorResponseError'
      required:
        - error
      description: Error response for internal server error
      title: InternalErrorResponse
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: >-
        JWT bearer token authentication. Obtain an access token from the
        Moveworks auth endpoint and include it in the Authorization header as
        'Bearer <token>'.

```

## Examples



**Request**

```json
{
  "input": {
    "text": "Who does John Doe report to?"
  }
}
```

**Response**

```json
{
  "response_id": "resp_32bt7rXXugeJjvE3pQzOk",
  "conversation_id": "conv_32bt7BMLhLyVzTUjfi35N",
  "status": "CREATED",
  "created_at": "2025-01-20T10:00:00Z"
}
```

**SDK Code**

```python Responses_createResponse_example
import requests

url = "https://api.moveworks.ai/assistant/v1/conversations/conv_32bt7BMLhLyVzTUjfi35N/responses"

payload = { "input": { "text": "Who does John Doe report to?" } }
headers = {
    "Assistant-Name": "acmecorp-conversations-rest-api",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript Responses_createResponse_example
const url = 'https://api.moveworks.ai/assistant/v1/conversations/conv_32bt7BMLhLyVzTUjfi35N/responses';
const options = {
  method: 'POST',
  headers: {
    'Assistant-Name': 'acmecorp-conversations-rest-api',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: '{"input":{"text":"Who does John Doe report to?"}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Responses_createResponse_example
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.moveworks.ai/assistant/v1/conversations/conv_32bt7BMLhLyVzTUjfi35N/responses"

	payload := strings.NewReader("{\n  \"input\": {\n    \"text\": \"Who does John Doe report to?\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Assistant-Name", "acmecorp-conversations-rest-api")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Responses_createResponse_example
require 'uri'
require 'net/http'

url = URI("https://api.moveworks.ai/assistant/v1/conversations/conv_32bt7BMLhLyVzTUjfi35N/responses")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Assistant-Name"] = 'acmecorp-conversations-rest-api'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"input\": {\n    \"text\": \"Who does John Doe report to?\"\n  }\n}"

response = http.request(request)
puts response.read_body
```

```java Responses_createResponse_example
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.moveworks.ai/assistant/v1/conversations/conv_32bt7BMLhLyVzTUjfi35N/responses")
  .header("Assistant-Name", "acmecorp-conversations-rest-api")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"input\": {\n    \"text\": \"Who does John Doe report to?\"\n  }\n}")
  .asString();
```

```php Responses_createResponse_example
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.moveworks.ai/assistant/v1/conversations/conv_32bt7BMLhLyVzTUjfi35N/responses', [
  'body' => '{
  "input": {
    "text": "Who does John Doe report to?"
  }
}',
  'headers' => [
    'Assistant-Name' => 'acmecorp-conversations-rest-api',
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp Responses_createResponse_example
using RestSharp;

var client = new RestClient("https://api.moveworks.ai/assistant/v1/conversations/conv_32bt7BMLhLyVzTUjfi35N/responses");
var request = new RestRequest(Method.POST);
request.AddHeader("Assistant-Name", "acmecorp-conversations-rest-api");
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"input\": {\n    \"text\": \"Who does John Doe report to?\"\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift Responses_createResponse_example
import Foundation

let headers = [
  "Assistant-Name": "acmecorp-conversations-rest-api",
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = ["input": ["text": "Who does John Doe report to?"]] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.moveworks.ai/assistant/v1/conversations/conv_32bt7BMLhLyVzTUjfi35N/responses")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```