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

# Send a chat message

POST https://astropods.com/api/v1/deployments/{deploymentId}/messaging/conversations/{conversationId}/messages
Content-Type: application/json

Sends a user message to the agent. `attachments` contains ready Files API
keys owned by the caller; file bytes are never inlined. The sidecar reloads
authoritative metadata, persists the user turn, then forwards it to the
agent. The assistant reply streams over the SSE endpoint and is persisted as
it arrives. Subscribe to the stream endpoint for live chunks. A conversation
owned by another user returns 404.


Reference: https://docs.astropods.com/api-reference/astro-ai-api/chat/send-chat-message

## OpenAPI Specification

```yaml
openapi: 3.1.0
info:
  title: astro-api
  version: 1.0.0
paths:
  /deployments/{deploymentId}/messaging/conversations/{conversationId}/messages:
    post:
      operationId: send-chat-message
      summary: Send a chat message
      description: >
        Sends a user message to the agent. `attachments` contains ready Files
        API

        keys owned by the caller; file bytes are never inlined. The sidecar
        reloads

        authoritative metadata, persists the user turn, then forwards it to the

        agent. The assistant reply streams over the SSE endpoint and is
        persisted as

        it arrives. Subscribe to the stream endpoint for live chunks. A
        conversation

        owned by another user returns 404.
      tags:
        - chat
      parameters:
        - name: deploymentId
          in: path
          description: Deployment ID
          required: true
          schema:
            type: string
        - name: conversationId
          in: path
          description: Conversation ID (client-chosen UUID v4)
          required: true
          schema:
            type: string
        - name: Authorization
          in: header
          description: OAuth 2.0 device flow or platform session token
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Message accepted (reply streams over the SSE endpoint)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MessagingSendMessageResponse'
        '400':
          description: Invalid request body or parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Authentication required
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Insufficient permissions for this account
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Resource not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: |
            The conversation has reached its per-thread message limit and is
            terminal. The response body carries the machine-readable code
            `message_limit_reached`; start a new conversation to continue.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '413':
          description: More than 16 files were attached to one message
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MessagingSendMessageRequest'
servers:
  - url: https://astropods.com/api/v1
    description: Astro AI API server
components:
  schemas:
    ChatFileReference:
      type: object
      properties:
        key:
          type: string
          description: Opaque key of a ready file owned by the caller.
      required:
        - key
      title: ChatFileReference
    MessagingSendMessageRequest:
      type: object
      properties:
        content:
          type: string
          description: The user's message text.
        attachments:
          type: array
          items:
            $ref: '#/components/schemas/ChatFileReference'
          description: >-
            Ready Files API keys owned by the caller. File bytes are not
            inlined.
      description: At least one of `content` or `attachments` must be non-empty.
      title: MessagingSendMessageRequest
    MessagingSendMessageResponse:
      type: object
      properties:
        message_id:
          type: string
        timestamp:
          type: string
          format: date-time
      title: MessagingSendMessageResponse
    Error:
      type: object
      properties:
        error:
          type: string
        details:
          type: string
      title: Error
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: OAuth 2.0 device flow or platform session token

```

## Examples



**Request**

```json
{}
```

**Response**

```json
{
  "message_id": "a3f1c9e2-7b4d-4f8a-9d3e-2b5c6f7a8d9e",
  "timestamp": "2024-01-15T09:30:00Z"
}
```

**SDK Code**

```python
import requests

url = "https://astropods.com/api/v1/deployments/deploymentId/messaging/conversations/conversationId/messages"

payload = {}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.json())
```

```javascript
const url = 'https://astropods.com/api/v1/deployments/deploymentId/messaging/conversations/conversationId/messages';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{}'
};

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

```go
package main

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

func main() {

	url := "https://astropods.com/api/v1/deployments/deploymentId/messaging/conversations/conversationId/messages"

	payload := strings.NewReader("{}")

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

	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
require 'uri'
require 'net/http'

url = URI("https://astropods.com/api/v1/deployments/deploymentId/messaging/conversations/conversationId/messages")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{}"

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

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

HttpResponse<String> response = Unirest.post("https://astropods.com/api/v1/deployments/deploymentId/messaging/conversations/conversationId/messages")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{}")
  .asString();
```

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

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://astropods.com/api/v1/deployments/deploymentId/messaging/conversations/conversationId/messages', [
  'body' => '{}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

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

```csharp
using RestSharp;

var client = new RestClient("https://astropods.com/api/v1/deployments/deploymentId/messaging/conversations/conversationId/messages");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [] as [String : Any]

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

let request = NSMutableURLRequest(url: NSURL(string: "https://astropods.com/api/v1/deployments/deploymentId/messaging/conversations/conversationId/messages")! 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()
```