# API Reference

The LLM Gateway provides OpenAI / Anthropic-compatible LLM endpoints (SaaS only). Requests and responses conform to each provider's native format, so you can use existing OpenAI SDKs / Anthropic SDKs as-is.

## Base URL

OpenAI

`https://api.fd.agenticstar.tm.softbank.jp/llm/v1`

Anthropic

`https://api.fd.agenticstar.tm.softbank.jp/llm`

## Authentication

| Method                 | Header                                 |
| ---------------------- | -------------------------------------- |
| API key (OpenAI)       | Authorization: Bearer agtstr\_...      |
| API key (Anthropic)    | x-api-key: agtstr\_...                 |
| Access token (CC flow) | Authorization: Bearer \<access\_token> |

For how to create API keys and clients, see [Setup](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/llm-gateway/guide/setup.md).

## Common Specifications

- `model` is required in the request body. Retrieve available models with `GET /v1/models`.
- The request body limit is 32MB.
- If IP restriction is configured, requests from disallowed networks return `403`.

## CORS

The LLM Gateway is intended for server-side use, and **direct calls from browsers (cross-origin) are not allowed by default**. Browser requests that include an `Origin` header are blocked unless an opt-in header is present (server-to-server calls send no `Origin`, so they are unaffected).

To call it directly from a browser, add one of the following headers to allow cross-origin access (`Access-Control-Allow-Origin: *` is returned):

| Header                                          | Description                                     |
| ----------------------------------------------- | ----------------------------------------------- |
| anthropic-dangerous-direct-browser-access: true | The Anthropic SDK's direct-browser-access flag. |
| x-agenticstar-allow-browser-access: true        | An equivalent custom header.                    |

> **warning**
>
> Calling directly from a browser exposes your API key to the client. Manage API keys on the server side and limit direct browser calls to trusted use cases.

## Endpoint List

| Method | Path                           | Compatibility | Description                 |
| ------ | ------------------------------ | ------------- | --------------------------- |
| POST   | /llm/v1/chat/completions       | OpenAI        | Chat completion             |
| POST   | /llm/v1/responses              | OpenAI        | Responses API               |
| POST   | /llm/v1/embeddings             | OpenAI        | Embedding vector generation |
| GET    | /llm/v1/models                 | OpenAI        | List of available models    |
| POST   | /llm/v1/messages               | Anthropic     | Message generation          |
| POST   | /llm/v1/messages/count\_tokens | Anthropic     | Token counting              |

The request / response details of each endpoint conform to the official OpenAI / Anthropic specifications.

- OpenAI compatible: [OpenAI API Reference](https://platform.openai.com/docs/api-reference)
- Anthropic compatible: [Anthropic API Reference](https://docs.anthropic.com/en/api)

## Request Examples

The request / response specifications of each endpoint conform to the official OpenAI / Anthropic specs. Representative call examples are shown below.

### OpenAI

### POST`/llm/v1/chat/completions`

**Chat completion**

**curl**

```curl
curl https://api.fd.agenticstar.tm.softbank.jp/llm/v1/chat/completions \
-H "Authorization: Bearer agtstr_..." \
-H "Content-Type: application/json" \
-d '{
  "model": "<model ID>",
  "messages": [{"role": "user", "content": "Hello"}]
}'
```

### Anthropic

### POST`/llm/v1/messages`

**Create a message**

**curl**

```curl
curl https://api.fd.agenticstar.tm.softbank.jp/llm/v1/messages \
-H "x-api-key: agtstr_..." \
-H "anthropic-version: 2023-06-01" \
-H "Content-Type: application/json" \
-d '{
  "model": "<model ID>",
  "max_tokens": 1024,
  "messages": [{"role": "user", "content": "Hello"}]
}'
```

## Streaming

Specify `"stream": true` in the request body to receive the response incrementally over SSE (Server-Sent Events). The format conforms to each provider's native streaming format.

**OpenAI** — `data: {chunk}` lines are sent and the stream ends with `data: [DONE]`.

```text
data: {"choices":[{"delta":{"content":"He"}}]}

data: {"choices":[{"delta":{"content":"llo"}}]}

data: [DONE]
```

**Anthropic** — events are delivered as `event:` / `data:` pairs (`message_start` → `content_block_delta` … → `message_stop`).

```text
event: content_block_delta
data: {"type":"content_block_delta","index":0,"delta":{"type":"text_delta","text":"He"}}

event: message_stop
data: {"type":"message_stop"}
```

## Errors

The main HTTP status codes that may be returned on error:

| Status                    | Description                                                                                                                                                                                                                           |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400 Bad Request`         | Invalid request (missing `model`, invalid JSON, requested model unavailable, blocked by the content filter, etc.)                                                                                                                     |
| `401 Unauthorized`        | API key / access token is invalid or missing                                                                                                                                                                                          |
| `403 Forbidden`           | Access from a network not allowed by IP restriction, an inactive license / insufficient entitlement, or the request was stopped by a security inspection in front of the API (the reference number, if any, is included in `message`) |
| `404 Not Found`           | The requested path does not exist, or the upstream provider returned 404 (an unavailable model returns `400`)                                                                                                                         |
| `413 Payload Too Large`   | The request body exceeds 32MB                                                                                                                                                                                                         |
| `429 Too Many Requests`   | Rate limit or quota exceeded. Hard quotas (e.g. daily budget) include `x-should-retry: false`. The rpm rate limit includes `Retry-After: 60`                                                                                          |
| `501 Not Implemented`     | The endpoint is not supported by the target provider (e.g. the Responses API)                                                                                                                                                         |
| `502 Bad Gateway`         | Communication error with the upstream provider, etc.                                                                                                                                                                                  |
| `503 Service Unavailable` | Authentication is temporarily unavailable. Please retry later. If the problem persists, contact the service administrator                                                                                                             |

### Error Response Format

The error body is returned in the native error format of the endpoint's provider family.

**OpenAI**

```json
{
  "error": {
    "type": "invalid_request_error",
    "message": "Missing required parameter: model.",
    "code": "missing_model"
  }
}
```

**Anthropic**

```json
{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "Missing required parameter: model."
  }
}
```

## Usage Logs

Usage (model, token count, cost, latency, etc.) can be viewed via the `llm-gateway-logs` endpoint in the [System Integration API Reference](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/reference/admin-api-reference.md) or in the admin console.
