---
title: "Messages"
method: POST
path: "/serverless/v1/messages"
tags: ["Serverless.Messages"]
---

# Messages

`POST /serverless/v1/messages`

## Request

- Base URL: `https://api.friendli.ai`
- URL: `https://api.friendli.ai/serverless/v1/messages`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/friendli/apis/friendli-suite-api-reference/docs/serverless/v1/messages/post.ts> (a function with typed inputs; its response is checked against the schema)

Generate responses using Anthropic Messages-style payloads.

## Headers

- `X-Friendli-Team` string, nullable: ID of team to run requests as (optional parameter).

## Request body

- ServerlessMessagesBody
  - `messages` MessagesInputMessage[], required: A list of conversation messages ordered from oldest to newest. Must contain at least one item.
    - `role` 'user' | 'assistant', required: Author role for this message turn. Use `user` for user input and `assistant` for prior assistant turns.
    - `content` union, required: Message payload. Supports plain string shorthand or a typed block array.
      - string
      - MessagesContentBlock[]
        - union
          - MessagesTextBlock
            - `type` 'text', required: Content block type. Must be `text`.
            - `text` string, required: Text content for this block.
          - MessagesImageBlock
            - `type` 'image', required: Content block type. Must be `image`.
            - `source` union, required
              - …
          - MessagesThinkingBlock
            - `type` 'thinking', required: Content block type. Must be `thinking`.
            - `thinking` string, required: Reasoning content for this block.
            - `signature` string, nullable: Optional signature associated with the reasoning content.
          - MessagesToolUseBlock
            - `type` 'tool_use', required: Content block type. Must be `tool_use`.
            - `id` string, nullable: Optional tool call identifier. Use this value to link follow-up `tool_result` blocks.
            - `name` string, required: Name of the tool to invoke.
            - `input` object, required: Tool input argument object.
          - MessagesToolResultBlock
            - `type` 'tool_result', required: Content block type. Must be `tool_result`.
            - `tool_use_id` string, required: Identifier of the related `tool_use` block this result answers.
            - `content` union: Tool result payload. Can be plain text, a list of objects, or null when no body is returned.
              - …
          - MessagesCompatibilityBlock
            - `type` 'document' | 'search_result' | 'redacted_thinking' | 'server_tool_use' | 'web_search_tool_result' | 'web_fetch_tool_result' | 'code_execution_tool_result' | 'bash_code_execution_tool_result' | 'text_editor_code_execution_tool_result' | 'tool_search_tool_result' | 'container_upload', required: Compatibility block type. These blocks are accepted for parsing compatibility and ignored for generation.
  - `max_tokens` integer, nullable: Maximum number of tokens to generate for the assistant response. Must be greater than 0 when provided.
  - `model` string, required: Code of the model to use. See [available model list](https://friendli.ai/docs/guides/model-apis/pricing#billing-methods).
  - `system` union: Optional top-level system instruction applied before conversation turns. Supports a plain string or an array of text blocks.
    - string
    - MessagesSystemTextBlock[]
      - `type` 'text', required: System block type. Must be `text`.
      - `text` string, required: System instruction text content.
  - `stream` boolean, nullable: Whether to stream output as server-sent events (`text/event-stream`). When false or omitted, returns a single JSON response.
  - `temperature` number, nullable: Sampling temperature. Lower values make outputs more deterministic; higher values increase diversity.
  - `top_p` number, nullable: Nucleus sampling parameter. The model samples from the smallest token set whose cumulative probability reaches `top_p`.
  - `top_k` integer, nullable: Limits sampling to the `k` most likely tokens at each decoding step.
  - `stop_sequences` string[], nullable: Stop strings that terminate generation when matched in output. The matched value is returned in `stop_sequence` when applicable.
  - `tools` MessagesToolDefinition[], nullable: Tool definitions available to the model. Use this to allow tool calls with structured arguments.
    - `name` string, required: Tool identifier used in model tool-call outputs. Keep this name stable and unique within the request.
    - `type` string, nullable: Tool category. If missing, empty, or `custom`, it is converted to a function tool. Any non-empty value other than `custom` is treated as a server-side tool and skipped.
    - `description` string, nullable: Natural-language description of what the tool does and when to call it.
    - `input_schema` object, nullable: JSON Schema describing tool arguments. The model uses this schema to construct the tool input object.
    - `strict` boolean, nullable: If true, applies stricter schema adherence when generating tool arguments.
  - `tool_choice` MessagesToolChoice
    - `type` 'auto' | 'any' | 'tool' | 'none', required: Tool-calling mode. `auto` lets the model decide, `any` requires at least one tool call, `tool` forces a named tool, and `none` disables tool calls.
    - `name` string, nullable: Tool name to force when `type=tool`. Ignored for other `type` values.
    - `disable_parallel_tool_use` boolean, nullable: If true, restricts the model to at most one tool call at a time. Must not be provided when `type=none`.
  - `thinking` MessagesThinkingConfig
    - `type` 'enabled' | 'disabled' | 'adaptive', required: Reasoning mode. `enabled` forces reasoning, `disabled` suppresses it, and `adaptive` lets the system decide.
    - `budget_tokens` integer, nullable: Reasoning token budget. Required when `type=enabled`; must not be provided when `type=disabled` or `type=adaptive`. If `max_tokens` is set, this must be smaller than `max_tokens`.
  - `output_config` MessagesOutputConfig
    - `effort` 'low' | 'medium' | 'high' | 'max', nullable: Relative generation effort level (`low`, `medium`, `high`, `max`). Higher effort can improve quality on harder prompts at the cost of additional compute.
    - `format` MessagesOutputFormat
      - `type` 'json_schema', nullable: Output format type. Set to `json_schema` to constrain output to a JSON schema.
      - `schema` object, nullable: JSON Schema object applied when `type` is `json_schema`.
  - `cache_control` object, nullable: Compatibility field accepted for request portability. Parsed but not used for generation.
  - `container` object, nullable: Compatibility field accepted for request portability. Parsed but not used for generation.
  - `context_manager` object, nullable: Compatibility field accepted for request portability. Parsed but not used for generation.
  - `inference_geo` object, nullable: Compatibility field accepted for request portability. Parsed but not used for generation.
  - `metadata` object, nullable: Compatibility field accepted for request portability. Parsed but not used for generation.
  - `service_tier` union: Compatibility field accepted for request portability. Parsed but not used for generation.
    - string
    - object

## Response `200`

Successfully generated a Messages-style response. For streaming (`text/event-stream`) event and chunk details, see [Messages chunk object](/openapi/model-apis/messages-chunk-object).

- ServerlessMessagesSuccess
  - `id` string, required: Unique identifier for this message response.
  - `type` 'message', required: Response object type (`message`).
  - `role` 'assistant', required: Role of the output message author (`assistant`).
  - `content` MessagesResponseContentBlock[], required: Assistant output blocks in generation order.
    - union
      - MessagesResponseThinkingBlock
        - `type` 'thinking', required: Content block type.
        - `thinking` string, required: Reasoning content returned by the model.
        - `signature` string, required: Signature associated with the reasoning content.
      - MessagesResponseTextBlock
        - `type` 'text', required: Content block type.
        - `text` string, required: Assistant-generated text for this block.
      - MessagesResponseToolUseBlock
        - `type` 'tool_use', required: Content block type.
        - `id` string, required: Identifier of the tool call emitted by the model.
        - `name` string, required: Name of the invoked tool.
        - `input` object, required: Parsed tool argument object generated by the model.
  - `stop_reason` 'end_turn' | 'max_tokens' | 'tool_use' | 'stop_sequence', nullable: Why generation stopped (`end_turn`, `max_tokens`, `tool_use`, `stop_sequence`).
  - `stop_sequence` string, nullable: Matched stop string when `stop_reason` is `stop_sequence`; otherwise null.
  - `usage` MessagesUsage, required
    - `input_tokens` integer, required: Number of billed input tokens for this request.
    - `output_tokens` integer, required: Number of billed output tokens generated by the model.
    - `cache_read_input_tokens` integer, nullable: Number of input tokens served from cache, when cache reads are applicable.
  - `model` string, nullable: Model used to generate the response.

## Other responses

- `422`: Unprocessable Entity

---

[API](https://skmtc.dev/friendli/apis/friendli-suite-api-reference.md) - [All operations](https://skmtc.dev/friendli/apis/friendli-suite-api-reference/llms.txt) - [OpenAPI document](https://skmtc.dev/friendli/apis/friendli-suite-api-reference/revisions/38fb43993a11?raw)