# User API Reference (Conversations, Organizations)

Endpoint specification and error codes for the user-facing APIs of the Marketplace edition. Call them with a user token obtained through an application (sign-in from an external tool). For the project APIs, see the [User API Reference (Projects)](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/api/reference/user-api-reference-projects.md). For the APIs called from a system integration, see the [System Integration API Reference](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/api/reference/api-reference.md).

## Base URL

All API requests are sent to the base URL below. Replace `<your-domain>` with the domain of your environment.

Marketplace

`https://<your-domain>/api`

Endpoint paths in this document are relative to the base URL.

## Authentication

Every API request must include a Bearer token in the `Authorization` header.

```text
Authorization: Bearer <access_token>
```

If the token is missing or invalid, `401 Unauthorized` is returned. The Marketplace edition applies no scope restrictions.

- Call the APIs on this page with a user token obtained through an application (sign-in from an external tool). Sign-in from an external tool is available only in environments where an administrator has opened its entrance ([API Setup Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/api/guide/setup-guide.md)).
- Calling them with a user token obtained in any other way (such as the token used when signing in to the Main Screen) returns `404 Not Found` for every endpoint.
- Chat, Conversation Management, File Management, Artifact Retrieval and Search can also be called with a system integration token ([System Integration API Reference](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/api/reference/api-reference.md)). Calling the [User](#user) and [Master Data](#master-data) APIs with a system integration token returns `404 Not Found`.

For how to obtain a token, see the [Authentication Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/api/guide/auth-guide.md) and the [Authentication API Reference](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/api/reference/auth-mp-ref.md).

> **Chat API**
>
> In the Marketplace edition the Chat API requires the `agentId` parameter and always runs with `stream: true`. See the [Call the API](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/api/quickstart/call-api.md) for details.

## Pagination

List endpoints support cursor-based pagination.

| Parameter | Type      | Description                                                                                                       |
| --------- | --------- | ----------------------------------------------------------------------------------------------------------------- |
| `limit`   | `integer` | Number of items per page (1-100). Defaults to 50.                                                                 |
| `cursor`  | `string`  | Cursor value for the next page. Pass the cursor from the previous response as is.                                 |
| `order`   | `string`  | Sort order: "asc" or "desc" (default). Any other value returns 400 Bad Request. Supported on some endpoints only. |

Responses include a `hasMore` field. While it is `true`, pass the `cursor` value in the next request to retrieve the following page.

Cursor-based pagination is available on the list endpoints of [Conversations](#conversations), [Messages](#conversations), [Files](#file-management) and [Projects](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/api/reference/user-api-reference-projects.md#projects). Treat `cursor` as opaque: do not interpret it, just pass the previous value back.

## Request handling

The APIs on this page handle requests as follows. See each endpoint's description and error responses for endpoint-specific handling.

- Query parameters and body fields that are not in the specification are ignored. However, a field that the service accepts but this page does not document may still return `400 Bad Request` if its type or value is invalid.
- An invalid value for a documented query parameter returns `400 Bad Request`.
- A malformed JSON body returns `400 Bad Request` (`invalid_body`).
- Sending a body with a `Content-Type` other than `application/json` to an endpoint that accepts a JSON body returns `415 Unsupported Media Type` (`unsupported_media_type`). File uploads return `415` for a body other than `multipart/form-data`. However, if reading the body fails first with `400` (malformed JSON) or `413` (over the size limit), that error is returned instead.
- A body field of the wrong type returns `400 Bad Request`.

## Chat

OpenAI-compatible Chat Completions API. Conversations with the agent are delivered via SSE (Server-Sent Events) streaming.

The Chat API consists of three endpoints. You can send messages, reconnect to existing conversations, and cancel conversations in progress.

SSE Streaming Guide

Detailed explanation of connection flow, response objects, Delta extensions, execution patterns, reconnection, and error handling

[View guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/api/guide/streaming-guide.md)

### Endpoint List

| メソッド | エンドポイント                                       | 説明                                                           | Scope (SaaS) |
| ---- | --------------------------------------------- | ------------------------------------------------------------ | ------------ |
| POST | `/v1/chat/completions`                        | Send a chat message and receive a response via SSE streaming | `chat:exec`  |
| GET  | `/v1/chat/completions/:conversationId`        | Reconnect to the SSE stream of a conversation in progress    | `chat:exec`  |
| POST | `/v1/chat/completions/:conversationId/cancel` | Cancel a conversation in progress                            | `chat:exec`  |

Note: The Marketplace edition does not require scopes (authentication only).

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

Send a message to the agent and receive a response via SSE streaming. Responses are delivered in OpenAI-compatible Chat Completion Chunk format.

#### Request Headers

| ヘッダー            | 必須 | 説明                      |
| --------------- | -- | ----------------------- |
| `Authorization` | 必須 | Bearer \<access\_token> |
| `Content-Type`  | 必須 | application/json        |

#### Request Body

| パラメータ            | 型         | 必須 | 説明                                                                                                                                                                                                                                                                                                                                                                                  |
| ---------------- | --------- | -- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `model`          | `string`  | 必須 | The model ID to use. Specify "AGENTIC STAR".                                                                                                                                                                                                                                                                                                                                        |
| `messages`       | `array`   | 必須 | Array of message objects. At least one user-role message is required. Even if multiple user messages are included, only the last one is processed. Conversation history is managed on the server side, so you do not need to send past exchanges in the messages array. To continue an existing conversation, specify the previous conversation ID in the conversationId parameter. |
| `stream`         | `boolean` | 必須 | Specify true. Currently, only streaming mode is supported.                                                                                                                                                                                                                                                                                                                          |
| `conversationId` | `string`  | —  | Specify a conversation ID to continue an existing conversation. If omitted, a new conversation is created.                                                                                                                                                                                                                                                                          |

#### Edition-Specific Parameters

Marketplace

|                |          |                                                                                                                                                                                                  |
| -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `agentId`      | `string` | The ID of the agent to use (required).                                                                                                                                                           |
| `outputFormat` | `string` | Response text format. "plain" (default) returns plain text with Markdown removed (diagrams dropped, code block bodies kept, and links become "text (URL)"). "markdown" preserves Markdown as-is. |

#### Message Object

| パラメータ     | 型                 | 必須 | 説明                                                                                                                                                        |
| --------- | ----------------- | -- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `role`    | `string`          | 必須 | Use "user". "assistant" / "system" are accepted but only "user" is effectively used as the starting point of the agent turn in the current implementation |
| `content` | `string \| array` | 必須 | The message content. A string, or an array of content parts (text / input\_file). The text to be processed must be 1 MB or less in UTF-8.                 |

#### Content Parts (Array Format)

When specifying content as an array, the following part types are available. You can combine text and files in a single message.

| type           | Parameter         | Description                                                        |
| -------------- | ----------------- | ------------------------------------------------------------------ |
| `"text"`       | `text (string)`   | Text message                                                       |
| `"input_file"` | `fileId (string)` | The `fileId` of an uploaded file. Up to 20 files total per request |

#### Request Example

**Create chat completion**

**curl**

```curl
curl -X POST https://<your-domain>/api/v1/chat/completions \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
  "model": "AGENTIC STAR",
  "agentId": "<your-agent-id>",
  "stream": true,
  "messages": [
    {
      "role": "user",
      "content": "Please analyze the sales data"
    }
  ]
}'
```

**Python**

```python
import requests

response = requests.post(
  "https://<your-domain>/api/v1/chat/completions",
  headers={
      "Authorization": f"Bearer {token}",
      "Content-Type": "application/json",
  },
  json={
      "model": "AGENTIC STAR",
      "agentId": "<your-agent-id>",
      "stream": True,
      "messages": [{"role": "user", "content": "Please analyze the sales data"}],
  },
  stream=True,
)

for line in response.iter_lines():
  if line:
      print(line.decode("utf-8"))
```

**TypeScript**

```typescript
const response = await fetch(
"https://<your-domain>/api/v1/chat/completions",
{
  method: "POST",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    model: "AGENTIC STAR",
    agentId: "<your-agent-id>",
    stream: true,
    messages: [{ role: "user", content: "Please analyze the sales data" }],
  }),
}
);

const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
const { done, value } = await reader.read();
if (done) break;
console.log(decoder.decode(value));
}
```

**Go**

```go
package main

import (
  "bufio"
  "bytes"
  "encoding/json"
  "fmt"
  "net/http"
  "strings"
)

func main() {
  token := "<access_token>" // Access token obtained in Step 1

  body, _ := json.Marshal(map[string]interface{}{
      "model":  "AGENTIC STAR",
      "agentId": "<your-agent-id>",
      "stream": true,
      "messages": []map[string]string{
          {"role": "user", "content": "Please analyze the sales data"},
      },
  })

  req, _ := http.NewRequest("POST",
      "https://<your-domain>/api/v1/chat/completions",
      bytes.NewReader(body))
  req.Header.Set("Authorization", "Bearer "+token)
  req.Header.Set("Content-Type", "application/json")

  resp, _ := http.DefaultClient.Do(req)
  defer resp.Body.Close()

  scanner := bufio.NewScanner(resp.Body)
  for scanner.Scan() {
      line := scanner.Text()
      if strings.HasPrefix(line, "data: ") {
          data := line[6:]
          if data == "[DONE]" { break }
          var chunk map[string]interface{}
          json.Unmarshal([]byte(data), &chunk)
          choices, _ := chunk["choices"].([]interface{})
          if len(choices) > 0 {
              delta, _ := choices[0].(map[string]interface{})["delta"].(map[string]interface{})
              if content, ok := delta["content"].(string); ok {
                  fmt.Print(content)
              }
          }
      }
  }
}
```

#### Response Headers

| Header              | Description                                                                |
| ------------------- | -------------------------------------------------------------------------- |
| `Content-Type`      | text/event-stream                                                          |
| `X-Conversation-Id` | Conversation ID. For new conversations, a server-generated ID is returned. |
| `X-Message-Id`      | The assistant response message ID.                                         |

#### SSE Response Format

Responses are delivered as SSE events in the following order. Each event is a JSON line prefixed with data:.

SSE Event Flow

1

<!-- -->

. `data: {"choices":[{"delta":{"role":"assistant"}}]}`

2

<!-- -->

. `data: {"choices":[{"delta":{"content":"..."}}]} × N`

3

<!-- -->

. `data: {"choices":[{"finishReason":"stop"}]}`

4

<!-- -->

. `data: [DONE]`

Responses are delivered via SSE (Server-Sent Events) streaming. Each chunk is in OpenAI-compatible ChatCompletionChunk format. For details on the connection lifecycle, response objects, agent extension fields, and error handling, see the [Streaming Guide](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/api/guide/streaming-guide.md).

#### Response Example

```text
data: {"createdAt":"2026-03-14T10:30:00Z","model":"AGENTIC STAR","choices":[{"index":0,"delta":{"role":"assistant"},"finishReason":null}]}

data: {"createdAt":"2026-03-14T10:30:00Z","model":"AGENTIC STAR","choices":[{"index":0,"delta":{"content":"Analyzing"},"finishReason":null}]}

data: {"createdAt":"2026-03-14T10:30:00Z","model":"AGENTIC STAR","choices":[{"index":0,"delta":{"content":" the sales data."},"finishReason":null}]}

data: {"createdAt":"2026-03-14T10:30:01Z","model":"AGENTIC STAR","choices":[{"index":0,"delta":{},"finishReason":"stop"}]}

data: [DONE]
```

#### Error Response

Errors before the SSE stream starts are returned in JSON format. Errors during the stream are delivered as SSE chunks.

| Status | Description                                                                                                                                                                                                                                                                                         |
| ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | Invalid request parameters (missing or malformed model / messages / stream / conversationId / role / content, or more than 20 input\_file parts in a single request). A malformed JSON body (`code: "invalid_body"`). Or the specified conversationId is archived (`code: "conversation_archived"`) |
| `415`  | The body Content-Type is not application/json (`code: "unsupported_media_type"`)                                                                                                                                                                                                                    |
| `403`  | The specified conversation is a project conversation (`code: "project_conversation"`. Messages cannot be sent to a project conversation)                                                                                                                                                            |
| `404`  | The specified input\_file `fileId` is not found                                                                                                                                                                                                                                                     |
| `409`  | The specified conversation is currently being processed                                                                                                                                                                                                                                             |

### GET`/v1/chat/completions/:conversationId`

Reconnect to the SSE stream of a conversation in progress. Use this when the agent is processing a long-running task or to recover after a network disconnection.

#### Path Parameters

| パラメータ            | 型        | 必須 | 説明                                         |
| ---------------- | -------- | -- | ------------------------------------------ |
| `conversationId` | `string` | 必須 | The ID of the conversation to reconnect to |

#### Request Example

**Resume SSE stream**

**curl**

```curl
curl https://<your-domain>/api/v1/chat/completions/550e8400-e29b-41d4-a716-446655440000 \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  "https://<your-domain>/api/v1/chat/completions/550e8400-e29b-41d4-a716-446655440000",
  headers={"Authorization": f"Bearer {token}"},
  stream=True,
)

for line in response.iter_lines():
  if line:
      print(line.decode("utf-8"))
```

**TypeScript**

```typescript
const response = await fetch(
"https://<your-domain>/api/v1/chat/completions/550e8400-e29b-41d4-a716-446655440000",
{
  headers: { "Authorization": "Bearer " + accessToken },
}
);

const reader = response.body.getReader();
const decoder = new TextDecoder();

while (true) {
const { done, value } = await reader.read();
if (done) break;
console.log(decoder.decode(value));
}
```

**Go**

```go
req, _ := http.NewRequest("GET",
  "https://<your-domain>/api/v1/chat/completions/550e8400-e29b-41d4-a716-446655440000",
  nil)
req.Header.Set("Authorization", "Bearer "+token)

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

scanner := bufio.NewScanner(resp.Body)
for scanner.Scan() {
  fmt.Println(scanner.Text())
}
```

#### Response (200 OK)

Reconnects to the SSE stream. The response format is the same as [POST /v1/chat/completions](#chat). The response headers include `X-Conversation-Id` and `X-Message-Id`. For detailed reconnection procedures, see the [Streaming Guide](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/api/guide/streaming-guide.md).

#### Error Response

| Status | Description                               |
| ------ | ----------------------------------------- |
| `400`  | Invalid conversationId                    |
| `404`  | Conversation not found or not in progress |

### POST`/v1/chat/completions/:conversationId/cancel`

Cancel a conversation in progress. Use this to abort the agent's execution.

#### Path Parameters

| パラメータ            | 型        | 必須 | 説明                                   |
| ---------------- | -------- | -- | ------------------------------------ |
| `conversationId` | `string` | 必須 | The ID of the conversation to cancel |

#### Request Body (optional)

| パラメータ       | 型        | 必須 | 説明                                                                                   |
| ----------- | -------- | -- | ------------------------------------------------------------------------------------ |
| `messageId` | `string` | —  | The ID of the message to cancel (UUID). If omitted, cancels the entire conversation. |

#### Request Example

**Cancel chat**

**curl**

```curl
curl -X POST https://<your-domain>/api/v1/chat/completions/550e8400-e29b-41d4-a716-446655440000/cancel \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json"
```

**Python**

```python
import requests

response = requests.post(
  "https://<your-domain>/api/v1/chat/completions/550e8400-e29b-41d4-a716-446655440000/cancel",
  headers={"Authorization": f"Bearer {token}"},
)

data = response.json()
print(f"Cancelled: {data['cancelled']}")
```

**TypeScript**

```typescript
const response = await fetch(
"https://<your-domain>/api/v1/chat/completions/550e8400-e29b-41d4-a716-446655440000/cancel",
{
  method: "POST",
  headers: { "Authorization": "Bearer " + accessToken },
}
);

const data = await response.json();
console.log("Cancelled: " + data.cancelled);
```

**Go**

```go
req, _ := http.NewRequest("POST",
  "https://<your-domain>/api/v1/chat/completions/550e8400-e29b-41d4-a716-446655440000/cancel",
  nil)
req.Header.Set("Authorization", "Bearer "+token)

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### Response Fields (200 OK)

| Field            | Type      | Description                                 |
| ---------------- | --------- | ------------------------------------------- |
| `conversationId` | `string`  | The ID of the cancelled conversation (UUID) |
| `cancelled`      | `boolean` | Always true on successful cancellation      |

#### Response Example

```json
{ "conversationId": "550e8400-...", "cancelled": true }
```

#### Error Response

| Status | Description                                                                                                                                                                                                                                                                                                                                                                  |
| ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | Invalid conversationId, messageId is not a string, the body is malformed JSON or not a JSON object (`code: "invalid_body"`), or the conversation is archived (`code: "conversation_archived"`)                                                                                                                                                                               |
| `415`  | The body Content-Type is not application/json (`code: "unsupported_media_type"`)                                                                                                                                                                                                                                                                                             |
| `404`  | Conversation not found, or the message cannot be canceled (`code: "message_not_found"`). `message_not_found` is returned in two cases: the message was just sent and could not be canceled after waiting about 10 seconds (sending again in a few seconds cancels it), or messageId is not a message of the conversation (sending again does not cancel it; check messageId) |

## Conversation Management

List, retrieve message history, delete, and update titles of conversations.

### Endpoint List

| メソッド   | エンドポイント                                      | 説明                            | Scope (SaaS)   |
| ------ | -------------------------------------------- | ----------------------------- | -------------- |
| GET    | `/v1/conversations`                          | List conversations            | `chat:history` |
| GET    | `/v1/conversations/:conversationId/messages` | Get message history           | `chat:history` |
| PATCH  | `/v1/conversations/:conversationId`          | Update conversation title     | `chat:history` |
| DELETE | `/v1/conversations/:conversationId`          | Delete a conversation         | `chat:history` |
| POST   | `/v1/conversations/:conversationId/restore`  | Restore archived conversation | `chat:history` |
| POST   | `/v1/conversations/:conversationId/read`     | Mark a conversation as read   | `chat:history` |

Note: The Marketplace edition does not require scopes (authentication only).

#### Operations on archived conversations

Conversations retrieved with `mode=archive` only support read operations (list / message history) and restoration. The following operations return a 400 error (`code: "conversation_archived"`).

| Operation                                                         | Behavior on archived conversations                                 |
| ----------------------------------------------------------------- | ------------------------------------------------------------------ |
| `GET /v1/conversations?mode=archive`                              | ✅ Allowed                                                          |
| `GET /v1/conversations/:id/messages`                              | ✅ Allowed (`messages[].archived: true` is added)                   |
| `PATCH /v1/conversations/:id`                                     | ❌ 400 `Archived conversations cannot be modified`                  |
| `DELETE /v1/conversations/:id`                                    | ❌ 400 `Archived conversations cannot be deleted via this endpoint` |
| `POST /v1/chat/completions` (continuing an existing conversation) | ❌ 400 `Cannot send messages to an archived conversation`           |
| `POST /v1/chat/completions/:id/cancel`                            | ❌ 400 `Cannot cancel an archived conversation`                     |
| `POST /v1/conversations/:id/restore`                              | ✅ Restore to active                                                |

### GET`/v1/conversations`

List conversations. Supports cursor-based pagination.

#### Query Parameters

| Parameter | Type      | Default    | Description                                                                                                                                                 |
| --------- | --------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `limit`   | `integer` | `50`       | Number of items to retrieve (1-100)                                                                                                                         |
| `cursor`  | `string`  | `—`        | Cursor for fetching the next page (cursor value from the previous response)                                                                                 |
| `order`   | `string`  | `"desc"`   | "asc" or "desc"                                                                                                                                             |
| `title`   | `string`  | `—`        | Filter by title                                                                                                                                             |
| `mode`    | `string`  | `"active"` | "active" (regular conversations) or "archive" (archived conversations). Switching `mode` queries a different data store, so `cursor` cannot be carried over |

#### Request Example

**List conversations**

**curl**

```curl
curl "https://<your-domain>/api/v1/conversations?limit=10&order=desc" \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  "https://<your-domain>/api/v1/conversations",
  headers={"Authorization": f"Bearer {token}"},
  params={"limit": 10, "order": "desc"},
)

data = response.json()
for conv in data["conversations"]:
  print(conv["title"], conv["conversationId"])
```

**TypeScript**

```typescript
const params = new URLSearchParams({ limit: "10", order: "desc" });
const response = await fetch(
"https://<your-domain>/api/v1/conversations?" + params,
{
  headers: { "Authorization": "Bearer " + accessToken },
}
);

const data = await response.json();
data.conversations.forEach((conv) => {
console.log(conv.title, conv.conversationId);
});
```

**Go**

```go
req, _ := http.NewRequest("GET",
  "https://<your-domain>/api/v1/conversations?limit=10&order=desc",
  nil)
req.Header.Set("Authorization", "Bearer "+token)

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### Response Fields (200 OK)

| Field                            | Type       | Description                                                                                                                                                                                                                             |
| -------------------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `conversations`                  | `array`    | Array of conversation objects                                                                                                                                                                                                           |
| `conversations[].conversationId` | `string`   | Unique identifier of the conversation (UUID)                                                                                                                                                                                            |
| `conversations[].title`          | `string`   | Conversation title                                                                                                                                                                                                                      |
| `conversations[].type`           | `string?`  | Kind of conversation: "chat" (chat) or "mail" (started from mail). Conversations of project steps are not in the list (their messages can be read by specifying the conversation ID). Not returned with `mode=archive`                  |
| `conversations[].createdAt`      | `string`   | Creation date and time (ISO 8601)                                                                                                                                                                                                       |
| `conversations[].updatedAt`      | `string`   | Last updated date and time (ISO 8601)                                                                                                                                                                                                   |
| `conversations[].archived`       | `boolean?` | Whether archived. Always `true` when retrieved via `mode=archive`. When `mode=active` returns this field as `true`, it is only because the conversation remained in archive state but was returned by the active list — usually omitted |
| `hasMore`                        | `boolean`  | Whether the next page exists                                                                                                                                                                                                            |
| `cursor`                         | `string`   | Cursor for fetching the next page. Included only when hasMore is true                                                                                                                                                                   |

#### Response Example

```json
{
  "conversations": [
    {
      "conversationId": "550e8400-e29b-41d4-a716-446655440000",
      "title": "Sales data analysis",
      "type": "chat",
      "createdAt": "2026-03-14T10:30:00Z",
      "updatedAt": "2026-03-14T10:35:00Z"
    }
  ],
  "hasMore": true,
  "cursor": "eyJrIjoiMjAyNi0wMy0xNFQxMDozMDowMC4wMDBaIn0"
}
```

#### Error Response

| Status | Description                                                                                                                                                                           |
| ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | Invalid limit parameter (outside the range of 1-100), mode is not "active" / "archive", order is not "asc" / "desc", or title is not a string (for example, specified more than once) |
| `502`  | The conversation list could not be retrieved (wait and retry)                                                                                                                         |

### GET`/v1/conversations/:conversationId/messages`

Retrieve the message history of a specified conversation. Cursor-based pagination is supported. Retrieving it does not mark the conversation as read (the same goes for reading via MCP or A2A). To mark it as read, call [Mark a conversation as read](#read-conversation).

#### Path Parameters

| パラメータ            | 型        | 必須 | 説明                     |
| ---------------- | -------- | -- | ---------------------- |
| `conversationId` | `string` | 必須 | Conversation ID (UUID) |

#### Query Parameters

| Parameter | Type      | Default  | Description                                                            |
| --------- | --------- | -------- | ---------------------------------------------------------------------- |
| `limit`   | `integer` | `50`     | Number of items per page (1-100)                                       |
| `cursor`  | `string`  | `—`      | Cursor for the next page (the cursor value from the previous response) |
| `order`   | `string`  | `"desc"` | "asc" or "desc"                                                        |

#### Request Example

**Get messages**

**curl**

```curl
curl https://<your-domain>/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/messages?order=asc \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
response = requests.get(
  "https://<your-domain>/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/messages",
  headers={"Authorization": f"Bearer {token}"},
  params={"order": "asc"},
)

messages = response.json()["messages"]
for msg in messages:
  print(f"[{msg['sender']}] {msg['text'][:50]}")
```

**TypeScript**

```typescript
const response = await fetch(
"https://<your-domain>/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/messages?order=asc",
{
  headers: { "Authorization": "Bearer " + accessToken },
}
);

const { messages } = await response.json();
messages.forEach((msg) => console.log("[" + msg.sender + "] " + msg.text));
```

**Go**

```go
req, _ := http.NewRequest("GET",
  "https://<your-domain>/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/messages?order=asc",
  nil)
req.Header.Set("Authorization", "Bearer "+token)

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### Response Fields (200 OK)

| Field                                 | Type       | Description                                                                                                                                                  |
| ------------------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `messages`                            | `array`    | Array of message objects                                                                                                                                     |
| `messages[].conversationId`           | `string`   | Conversation ID (UUID)                                                                                                                                       |
| `messages[].messageId`                | `string`   | Unique identifier of the message                                                                                                                             |
| `messages[].sender`                   | `string`   | Sender. "User" or "AI"                                                                                                                                       |
| `messages[].text`                     | `string`   | Message body text                                                                                                                                            |
| `messages[].createdAt`                | `string`   | Creation date and time (ISO 8601)                                                                                                                            |
| `messages[].updatedAt`                | `string`   | Last updated date and time (ISO 8601)                                                                                                                        |
| `messages[].status`                   | `object`   | Message processing status                                                                                                                                    |
| `messages[].status.processing`        | `boolean`  | Whether the agent is currently processing                                                                                                                    |
| `messages[].status.unfinished`        | `boolean`  | Whether the agent response was interrupted                                                                                                                   |
| `messages[].tasks`                    | `array`    | Array of tasks executed by the agent (see below)                                                                                                             |
| `messages[].deliverables`             | `array`    | Array of artifacts generated by the agent. Included only when present                                                                                        |
| `messages[].deliverables[].filename`  | `string`   | Artifact file name                                                                                                                                           |
| `messages[].deliverables[].filepath`  | `string`   | Artifact file path                                                                                                                                           |
| `messages[].deliverables[].source`    | `string`   | `"agent"` (agent-generated) or `"user"` (user-uploaded)                                                                                                      |
| `messages[].deliverables[].isPrimary` | `boolean`  | Whether it is a primary artifact                                                                                                                             |
| `messages[].deliverables[].createdAt` | `string`   | Creation date and time (ISO 8601 format)                                                                                                                     |
| `messages[].deliverables[].mimeType`  | `string`   | MIME type (e.g., `"application/pdf"`, `"text/markdown"`). `"application/octet-stream"` when it cannot be determined                                          |
| `messages[].deliverables[].size`      | `number?`  | File size (bytes). Omitted when 0 or below                                                                                                                   |
| `messages[].files`                    | `array?`   | Array of user-uploaded files. Included only when present for messages with `sender: "User"`                                                                  |
| `messages[].files[].fileId`           | `string`   | Unique identifier of the file (UUID)                                                                                                                         |
| `messages[].files[].mimeType`         | `string`   | MIME type (e.g., `"image/png"`, `"application/pdf"`)                                                                                                         |
| `messages[].files[].width`            | `number?`  | Image width in pixels. Only for image files                                                                                                                  |
| `messages[].files[].height`           | `number?`  | Image height in pixels. Only for image files                                                                                                                 |
| `messages[].archived`                 | `boolean?` | `true` only for messages retrieved via archive. Added when viewing the message history of a conversation retrieved with `GET /v1/conversations?mode=archive` |
| `hasMore`                             | `boolean`  | Whether a next page exists                                                                                                                                   |
| `cursor`                              | `string`   | Cursor for the next page. Included only when hasMore is true                                                                                                 |

#### Task Object

| Field            | Type      | Description                                                                                                                                                                                                                       |
| ---------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `messageId`      | `string`  | ID of the message the task belongs to                                                                                                                                                                                             |
| `conversationId` | `string`  | ID of the conversation the task belongs to                                                                                                                                                                                        |
| `callId`         | `string?` | Tool call ID. In Complex Path, multiple tasks share the same callId and identify a sequence of steps for the same tool call                                                                                                       |
| `actionType`     | `string`  | Type of task (e.g., tool execution, code generation)                                                                                                                                                                              |
| `title`          | `string?` | Task title. Omitted when not present                                                                                                                                                                                              |
| `description`    | `string?` | Task description. Omitted when not present                                                                                                                                                                                        |
| `status`         | `string`  | Task status. One of: "in\_progress" / "completed" / "failed" / "error" / "pending"                                                                                                                                                |
| `content`        | `string?` | Task execution result text. Omitted when not present                                                                                                                                                                              |
| `metadata`       | `object?` | Auxiliary information that varies by actionType (sub\_event\_type, url, filepath, etc.). See the [Streaming Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/api/guide/streaming-guide.md) for details |
| `files`          | `array?`  | Files related to the task (`filename` / `size` / `filepath` / `mimeType?`. `mimeType` is omitted when it cannot be determined). The array itself is omitted when there are no related files                                       |
| `timestamp`      | `number`  | Timestamp of task execution (Unix milliseconds)                                                                                                                                                                                   |
| `createdAt`      | `string`  | Creation date and time (ISO 8601)                                                                                                                                                                                                 |
| `updatedAt`      | `string`  | Last updated date and time (ISO 8601)                                                                                                                                                                                             |

<!-- -->

> **Safely ignore unknown fields**
>
> Future implementations may add new fields to `actionType` / `metadata`. Client implementations should safely ignore any fields not listed in this table. For detailed metadata structure, refer to the [Streaming Guide — Task data model](https://developers.fd.agenticstar.tm.softbank.jp/docs/marketplace/api/guide/streaming-guide.md#task-data-model).

#### Response Example

```json
{
  "messages": [
    {
      "conversationId": "550e8400-...",
      "messageId": "msg-abc123",
      "sender": "User",
      "text": "Please analyze the sales data",
      "createdAt": "2026-03-14T10:30:00Z",
      "updatedAt": "2026-03-14T10:30:00Z",
      "status": { "processing": false, "unfinished": false },
      "tasks": []
    }
  ],
  "hasMore": false
}
```

#### Pagination

Specify `limit` to fetch items in pages. While `hasMore` is `true`, pass the `cursor` from the response to the next request as-is.

**Request example**

**curl**

```bash
# First page
curl "https://<your-domain>/api/v1/conversations/<conversation_id>/messages?limit=50" \
-H "Authorization: Bearer <access_token>"

# Second page (use the cursor returned by the first page)
curl "https://<your-domain>/api/v1/conversations/<conversation_id>/messages?limit=50&cursor=<cursor>" \
-H "Authorization: Bearer <access_token>"
```

If `limit` is omitted, 50 items are returned. To fetch everything, keep following the `cursor` until `hasMore` becomes `false`.

> **Using the cursor**
>
> The `cursor` represents a position in the result set. Do not change `order` while you are following the same cursor — changing the conditions changes the target set and causes duplicated or skipped items.
>
> Items may also be duplicated or skipped across pages if messages are added or removed while you are paging.

#### Error Response

| Status | Description                                              |
| ------ | -------------------------------------------------------- |
| `400`  | Invalid conversationId format                            |
| `400`  | limit is not an integer between 1 and 100                |
| `400`  | cursor is invalid (not a value from a previous response) |
| `400`  | order is not "asc" / "desc"                              |
| `404`  | Conversation not found                                   |

<!-- -->

### PATCH`/v1/conversations/:conversationId`

Update the title of a conversation.

#### Path Parameters

| パラメータ            | 型        | 必須 | 説明                     |
| ---------------- | -------- | -- | ---------------------- |
| `conversationId` | `string` | 必須 | Conversation ID (UUID) |

#### Request Body

| パラメータ   | 型        | 必須 | 説明                                              |
| ------- | -------- | -- | ----------------------------------------------- |
| `title` | `string` | 必須 | New conversation title (200 characters or less) |

#### Request Example

**Update conversation**

**curl**

```curl
curl -X PATCH https://<your-domain>/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000 \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{ "title": "New title" }'
```

**Python**

```python
import requests

response = requests.patch(
  "https://<your-domain>/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000",
  headers={"Authorization": f"Bearer {token}"},
  json={"title": "New title"},
)

data = response.json()
print(f"Updated: {data['title']}")
```

**TypeScript**

```typescript
const response = await fetch(
"https://<your-domain>/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000",
{
  method: "PATCH",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ title: "New title" }),
}
);

const data = await response.json();
console.log("Updated: " + data.title);
```

**Go**

```go
payload := map[string]string{"title": "New title"}
body, _ := json.Marshal(payload)

req, _ := http.NewRequest("PATCH",
  "https://<your-domain>/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000",
  bytes.NewBuffer(body))
req.Header.Set("Authorization", "Bearer "+token)
req.Header.Set("Content-Type", "application/json")

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()
```

#### Response Fields (200 OK)

| Field            | Type     | Description                                                                           |
| ---------------- | -------- | ------------------------------------------------------------------------------------- |
| `conversationId` | `string` | Conversation ID (UUID)                                                                |
| `title`          | `string` | Updated title                                                                         |
| `type`           | `string` | Kind of conversation: "chat", "mail", or "project" (a conversation of a project step) |
| `createdAt`      | `string` | Creation timestamp (ISO 8601)                                                         |
| `updatedAt`      | `string` | Last update timestamp (ISO 8601)                                                      |

#### Response Example

```json
{
  "conversationId": "550e8400-...",
  "title": "New title",
  "type": "chat",
  "createdAt": "2026-03-14T10:30:00.000Z",
  "updatedAt": "2026-03-14T12:00:00.000Z"
}
```

#### Error Response

| Status | Description                                                                                                                                                                |
| ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | title is missing, empty, or exceeds 200 characters, the body is malformed JSON (`code: "invalid_body"`), or the conversation is archived (`code: "conversation_archived"`) |
| `415`  | The body Content-Type is not application/json (`code: "unsupported_media_type"`)                                                                                           |
| `404`  | Conversation not found                                                                                                                                                     |

### DELETE`/v1/conversations/:conversationId`

Delete a conversation.

#### Path Parameters

| パラメータ            | 型        | 必須 | 説明                     |
| ---------------- | -------- | -- | ---------------------- |
| `conversationId` | `string` | 必須 | Conversation ID (UUID) |

#### Request Example

**Delete conversation**

**curl**

```curl
curl -X DELETE https://<your-domain>/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000 \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.delete(
  "https://<your-domain>/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000",
  headers={"Authorization": f"Bearer {token}"},
)

data = response.json()
print(f"Deleted: {data['deleted']}")
```

**TypeScript**

```typescript
const response = await fetch(
"https://<your-domain>/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000",
{
  method: "DELETE",
  headers: { "Authorization": "Bearer " + accessToken },
}
);

const data = await response.json();
console.log("Deleted: " + data.deleted);
```

**Go**

```go
req, _ := http.NewRequest("DELETE",
  "https://<your-domain>/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000",
  nil)
req.Header.Set("Authorization", "Bearer "+token)

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### Response Fields (200 OK)

| Field            | Type      | Description                           |
| ---------------- | --------- | ------------------------------------- |
| `conversationId` | `string`  | ID of the deleted conversation (UUID) |
| `deleted`        | `boolean` | Always true on successful deletion    |

#### Response Example

```json
{ "conversationId": "550e8400-...", "deleted": true }
```

#### Error Response

| Status | Description                                                                                                                                                                       |
| ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | Invalid conversationId, or the conversation is archived (`code: "conversation_archived"`; use `POST /v1/conversations/:id/restore` to restore it)                                 |
| `404`  | Conversation not found                                                                                                                                                            |
| `409`  | Conversation cannot be deleted because it is currently being processed, or it is a project conversation (`code: "project_conversation"`. Project conversations cannot be deleted) |

### POST`/v1/conversations/:conversationId/restore`

Restore an archived conversation back to active. After restoration, the conversation can be edited, continued, and deleted just like a regular conversation.

#### Path Parameters

| パラメータ            | 型        | 必須 | 説明                                     |
| ---------------- | -------- | -- | -------------------------------------- |
| `conversationId` | `string` | 必須 | ID of the archived conversation (UUID) |

#### Request Example

**Restore archived conversation**

**curl**

```curl
curl -X POST https://<your-domain>/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/restore \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.post(
  "https://<your-domain>/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/restore",
  headers={"Authorization": f"Bearer {token}"},
)

data = response.json()
print(f"Restored: {data['restored']}")
```

**TypeScript**

```typescript
const response = await fetch(
"https://<your-domain>/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/restore",
{
  method: "POST",
  headers: { "Authorization": "Bearer " + accessToken },
}
);

const data = await response.json();
console.log("Restored: " + data.restored);
```

**Go**

```go
req, _ := http.NewRequest("POST",
  "https://<your-domain>/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/restore",
  nil)
req.Header.Set("Authorization", "Bearer "+token)

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### Response Fields (200 OK)

| Field            | Type      | Description                             |
| ---------------- | --------- | --------------------------------------- |
| `conversationId` | `string`  | ID of the restored conversation (UUID)  |
| `restored`       | `boolean` | Always `true` on successful restoration |

#### Response Example

```json
{ "conversationId": "550e8400-...", "restored": true }
```

#### Error Response

| Status | Description                                                                                       |
| ------ | ------------------------------------------------------------------------------------------------- |
| `400`  | Invalid conversationId                                                                            |
| `404`  | No matching conversation in archive, or it is already active (archive state is not distinguished) |

### POST`/v1/conversations/:conversationId/read`

Marks a conversation as read. Reading the messages of a conversation through the API (REST, MCP, or A2A) does not mark it as read, so call this when you want to record that it was read. The read position never moves back (specifying an earlier message does not move it before where it is).

<!-- -->

#### Path Parameters

| パラメータ            | 型        | 必須 | 説明                     |
| ---------------- | -------- | -- | ---------------------- |
| `conversationId` | `string` | 必須 | Conversation ID (UUID) |

#### Request Body (optional)

The body can be omitted. When you send one, use `Content-Type: application/json`.

| パラメータ       | 型        | 必須 | 説明                                                                                                                                                                                                 |
| ----------- | -------- | -- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `messageId` | `string` | —  | ID of the last message you read. If omitted, the conversation is marked as read up to its latest message at that moment (specify it to avoid marking messages that arrived while you were reading) |

#### Request Example

**Mark a conversation as read**

**curl**

```curl
curl -X POST https://<your-domain>/api/v1/conversations/550e8400-e29b-41d4-a716-446655440000/read \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{"messageId": "7c9e6679-7425-40de-944b-e07fc1f90ae7"}'
```

#### Response (204 No Content)

There is no body.

#### Error Responses

| Status | Description                                                                                                                               |
| ------ | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | Invalid conversationId, messageId, or body (`invalid_parameter`, etc.), or the conversation is archived (`conversation_archived`)         |
| `404`  | The conversation does not exist or is not yours (`conversation_not_found`), or messageId is not in the conversation (`message_not_found`) |
| `415`  | The body is not application/json                                                                                                          |

## File Management

Upload, retrieve, and delete files.

### Endpoint List

| メソッド   | エンドポイント                     | 説明              | Scope (SaaS) |
| ------ | --------------------------- | --------------- | ------------ |
| GET    | `/v1/files`                 | List files      | `chat:file`  |
| POST   | `/v1/files`                 | Upload a file   | `chat:file`  |
| GET    | `/v1/files/:fileId/content` | Download a file | `chat:file`  |
| DELETE | `/v1/files/:fileId`         | Delete a file   | `chat:file`  |

Note: The Marketplace edition does not require scopes (authentication only).

### POST`/v1/files`

Upload a file.

#### Request Body (multipart/form-data)

| パラメータ      | 型        | 必須 | 説明                                       |
| ---------- | -------- | -- | ---------------------------------------- |
| `file`     | `file`   | 必須 | The file to upload. Maximum size 512 MB. |
| `filename` | `string` | 必須 | File name                                |

#### Request Example

**Upload file**

**curl**

```curl
curl -X POST https://<your-domain>/api/v1/files \
-H "Authorization: Bearer <access_token>" \
-F "file=@report.pdf" \
-F "filename=report.pdf"
```

**Python**

```python
import requests

with open("report.pdf", "rb") as f:
  response = requests.post(
      "https://<your-domain>/api/v1/files",
      headers={"Authorization": f"Bearer {token}"},
      files={"file": f},
      data={"filename": "report.pdf"},
  )
  data = response.json()
  print(data["fileId"])
```

**TypeScript**

```typescript
const formData = new FormData();
formData.append("file", file); // File object from input
formData.append("filename", "report.pdf");

const response = await fetch(
"https://<your-domain>/api/v1/files",
{
  method: "POST",
  headers: { "Authorization": "Bearer " + accessToken },
  body: formData,
}
);

const data = await response.json();
console.log(data.fileId);
```

**Go**

```go
file, _ := os.Open("report.pdf")
defer file.Close()

body := &bytes.Buffer{}
writer := multipart.NewWriter(body)
part, _ := writer.CreateFormFile("file", "report.pdf")
io.Copy(part, file)
writer.WriteField("filename", "report.pdf")
writer.Close()

req, _ := http.NewRequest("POST",
  "https://<your-domain>/api/v1/files",
  body)
req.Header.Set("Authorization", "Bearer "+token)
req.Header.Set("Content-Type", writer.FormDataContentType())
```

#### Response Fields (201 Created)

| Field       | Type      | Description                                 |
| ----------- | --------- | ------------------------------------------- |
| `fileId`    | `string`  | Unique identifier of the file (UUID)        |
| `filename`  | `string`  | File name                                   |
| `bytes`     | `integer` | File size (bytes)                           |
| `createdAt` | `string`  | Creation date and time (ISO 8601)           |
| `width`     | `integer` | Image width (pixels). Only for image files  |
| `height`    | `integer` | Image height (pixels). Only for image files |

#### Response Example

```json
{
  "fileId": "550e8400-e29b-41d4-a716-446655440001",
  "filename": "report.pdf",
  "bytes": 1048576,
  "createdAt": "2026-03-14T10:30:00.000Z"
}
```

#### Error Response

| Status | Description                                                                                                         |
| ------ | ------------------------------------------------------------------------------------------------------------------- |
| `400`  | file or filename parameter is missing, file size exceeds 512 MB, or the uploaded image file is corrupted or invalid |
| `415`  | The body is not multipart/form-data (`code: "unsupported_media_type"`)                                              |

### GET`/v1/files`

List files. Cursor-based pagination is supported.

#### Query Parameters

| Parameter | Type      | Default  | Description                                                            |
| --------- | --------- | -------- | ---------------------------------------------------------------------- |
| `limit`   | `integer` | `50`     | Number of items per page (1-100)                                       |
| `cursor`  | `string`  | `—`      | Cursor for the next page (the cursor value from the previous response) |
| `order`   | `string`  | `"desc"` | "asc" or "desc"                                                        |

#### Request Example

**List files**

**curl**

```curl
curl https://<your-domain>/api/v1/files?order=desc \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  "https://<your-domain>/api/v1/files",
  headers={"Authorization": f"Bearer {token}"},
  params={"order": "desc"},
)

files = response.json()["files"]
for file in files:
  print(f"{file['filename']} ({file['bytes']} bytes)")
```

**TypeScript**

```typescript
const params = new URLSearchParams({ order: "desc" });
const response = await fetch(
"https://<your-domain>/api/v1/files?" + params,
{
  headers: { "Authorization": "Bearer " + accessToken },
}
);

const data = await response.json();
data.files.forEach((file) => {
console.log(file.filename + " (" + file.bytes + " bytes)");
});
```

**Go**

```go
req, _ := http.NewRequest("GET",
  "https://<your-domain>/api/v1/files?order=desc",
  nil)
req.Header.Set("Authorization", "Bearer "+token)

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### Response Fields (200 OK)

| Field               | Type      | Description                                                  |
| ------------------- | --------- | ------------------------------------------------------------ |
| `files`             | `array`   | Array of file objects                                        |
| `files[].fileId`    | `string`  | Unique identifier of the file (UUID)                         |
| `files[].filename`  | `string`  | File name                                                    |
| `files[].bytes`     | `integer` | File size (bytes)                                            |
| `files[].createdAt` | `string`  | Creation date and time (ISO 8601)                            |
| `files[].width`     | `integer` | Image width (pixels). Only for image files                   |
| `files[].height`    | `integer` | Image height (pixels). Only for image files                  |
| `hasMore`           | `boolean` | Whether a next page exists                                   |
| `cursor`            | `string`  | Cursor for the next page. Included only when hasMore is true |

#### Response Example

```json
{
  "files": [
    {
      "fileId": "550e8400-e29b-41d4-a716-446655440001",
      "filename": "report.pdf",
      "bytes": 1048576,
      "createdAt": "2026-03-14T10:30:00.000Z"
    }
  ],
  "hasMore": false
}
```

#### Pagination

Specify `limit` to fetch items in pages. While `hasMore` is `true`, pass the `cursor` from the response to the next request as-is.

**Request example**

**curl**

```bash
# First page
curl "https://<your-domain>/api/v1/files?limit=50&order=desc" \
-H "Authorization: Bearer <access_token>"

# Second page (use the cursor returned by the first page)
curl "https://<your-domain>/api/v1/files?limit=50&order=desc&cursor=<cursor>" \
-H "Authorization: Bearer <access_token>"
```

If `limit` is omitted, 50 items are returned. To fetch everything, keep following the `cursor` until `hasMore` becomes `false`.

> **Using the cursor**
>
> The `cursor` represents a position in the result set. Do not change `order` while you are following the same cursor — changing the conditions changes the target set and causes duplicated or skipped items.
>
> Items may also be duplicated or skipped across pages if files are added or removed while you are paging.

#### Error Response

| Status | Description                                              |
| ------ | -------------------------------------------------------- |
| `400`  | limit is not an integer between 1 and 100                |
| `400`  | cursor is invalid (not a value from a previous response) |
| `400`  | order is not "asc" / "desc"                              |

### GET`/v1/files/:fileId/content`

Download a file.

#### Path Parameters

| パラメータ    | 型        | 必須 | 説明             |
| -------- | -------- | -- | -------------- |
| `fileId` | `string` | 必須 | File ID (UUID) |

#### Request Example

**Download file**

**curl**

```curl
curl https://<your-domain>/api/v1/files/550e8400-e29b-41d4-a716-446655440001/content \
-H "Authorization: Bearer <access_token>" \
-o downloaded_file.pdf
```

**Python**

```python
import requests

response = requests.get(
  "https://<your-domain>/api/v1/files/550e8400-e29b-41d4-a716-446655440001/content",
  headers={"Authorization": f"Bearer {token}"},
  stream=True,
)

with open("downloaded_file.pdf", "wb") as f:
  for chunk in response.iter_content(chunk_size=8192):
      f.write(chunk)
```

**TypeScript**

```typescript
const fs = require("fs");
const response = await fetch(
"https://<your-domain>/api/v1/files/550e8400-e29b-41d4-a716-446655440001/content",
{
  headers: { "Authorization": "Bearer " + accessToken },
}
);

const buffer = await response.arrayBuffer();
fs.writeFileSync("downloaded_file.pdf", new Uint8Array(buffer));
```

**Go**

```go
req, _ := http.NewRequest("GET",
  "https://<your-domain>/api/v1/files/550e8400-e29b-41d4-a716-446655440001/content",
  nil)
req.Header.Set("Authorization", "Bearer "+token)

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

file, _ := os.Create("downloaded_file.pdf")
defer file.Close()
io.Copy(file, resp.Body)
```

#### Response (200 OK)

The file binary data is returned as a stream.

| Response Header       | Description                     |
| --------------------- | ------------------------------- |
| `Content-Type`        | MIME type of the file           |
| `Content-Length`      | File size (bytes)               |
| `Content-Disposition` | attachment; filename="filename" |

#### Error Response

| Status | Description           |
| ------ | --------------------- |
| `400`  | Invalid fileId format |
| `404`  | File not found        |

### DELETE`/v1/files/:fileId`

Delete a file.

#### Path Parameters

| パラメータ    | 型        | 必須 | 説明             |
| -------- | -------- | -- | -------------- |
| `fileId` | `string` | 必須 | File ID (UUID) |

#### Request Example

**Delete file**

**curl**

```curl
curl -X DELETE https://<your-domain>/api/v1/files/550e8400-e29b-41d4-a716-446655440001 \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.delete(
  "https://<your-domain>/api/v1/files/550e8400-e29b-41d4-a716-446655440001",
  headers={"Authorization": f"Bearer {token}"},
)

data = response.json()
print(f"File deleted: {data['deleted']}")
```

**TypeScript**

```typescript
const response = await fetch(
"https://<your-domain>/api/v1/files/550e8400-e29b-41d4-a716-446655440001",
{
  method: "DELETE",
  headers: { "Authorization": "Bearer " + accessToken },
}
);

const data = await response.json();
console.log("File deleted: " + data.deleted);
```

**Go**

```go
req, _ := http.NewRequest("DELETE",
  "https://<your-domain>/api/v1/files/550e8400-e29b-41d4-a716-446655440001",
  nil)
req.Header.Set("Authorization", "Bearer "+token)

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### Response Fields (200 OK)

| Field     | Type      | Description                        |
| --------- | --------- | ---------------------------------- |
| `fileId`  | `string`  | ID of the deleted file (UUID)      |
| `deleted` | `boolean` | Always true on successful deletion |

#### Response Example

```json
{ "fileId": "550e8400-e29b-41d4-a716-446655440001", "deleted": true }
```

#### Error Response

| Status | Description           |
| ------ | --------------------- |
| `400`  | Invalid fileId format |
| `404`  | File not found        |

## Artifact Retrieval

Retrieve artifact files generated by the agent.

### Endpoint List

| メソッド | エンドポイント           | 説明                   | Scope (SaaS) |
| ---- | ----------------- | -------------------- | ------------ |
| GET  | `/v1/files/proxy` | Get an artifact file | `chat:exec`  |

Note: The Marketplace edition does not require scopes (authentication only).

### GET`/v1/files/proxy`

Download an artifact file by specifying the path obtained from `deliverables[].filepath` in the message history.

<!-- -->

The Marketplace edition does not enforce scopes. Any authenticated token can download artifacts.

<!-- -->

<!-- -->

#### Query Parameters

| パラメータ  | 型        | 必須 | 説明                                                                                 |
| ------ | -------- | -- | ---------------------------------------------------------------------------------- |
| `path` | `string` | 必須 | Artifact file path (obtained from deliverables\[].filepath in the message history) |

#### Request Example

**Get artifact file**

**curl**

```curl
curl "https://<your-domain>/api/v1/files/proxy?path=/path/to/artifact.xlsx" \
-H "Authorization: Bearer <access_token>" \
-o artifact.xlsx
```

**Python**

```python
import requests

response = requests.get(
  "https://<your-domain>/api/v1/files/proxy",
  headers={"Authorization": "Bearer " + token},
  params={"path": "/path/to/artifact.xlsx"},
  stream=True,
)

with open("artifact.xlsx", "wb") as f:
  for chunk in response.iter_content(chunk_size=8192):
      f.write(chunk)
```

**TypeScript**

```typescript
const params = new URLSearchParams({
path: "/path/to/artifact.xlsx",
});
const response = await fetch(
"https://<your-domain>/api/v1/files/proxy?" + params,
{
  headers: { "Authorization": "Bearer " + accessToken },
}
);

const blob = await response.blob();
```

**Go**

```go
req, _ := http.NewRequest("GET",
  "https://<your-domain>/api/v1/files/proxy?path=%2Fpath%2Fto%2Fartifact.xlsx",
  nil)
req.Header.Set("Authorization", "Bearer "+token)

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

out, _ := os.Create("artifact.xlsx")
defer out.Close()
io.Copy(out, resp.Body)
```

#### Response (200 OK)

The artifact file binary data is returned as a stream.

| Response Header  | Description           |
| ---------------- | --------------------- |
| `Content-Type`   | MIME type of the file |
| `Content-Length` | File size (bytes)     |

#### Error Response

| Status | Description                                                                                                                              |
| ------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | path parameter is missing or has an invalid format                                                                                       |
| `404`  | File not found (`code: "not_found"` and others)                                                                                          |
| `500`  | Unknown storage error (`code: "unknown"`)                                                                                                |
| `502`  | Storage access was denied (`code: "storage_forbidden"`), or storage rejected the request (`code: "rejected"`). Contact the administrator |
| `503`  | Storage is temporarily busy (`code: "rate_limited"`) or temporarily unavailable (`code: "transient"`). Wait and retry                    |

## Search

Full-text search messages.

### Endpoint List

| メソッド | エンドポイント               | 説明                        | Scope (SaaS)   |
| ---- | --------------------- | ------------------------- | -------------- |
| GET  | `/v1/search/messages` | Full-text search messages | `chat:history` |

Note: The Marketplace edition does not require scopes (authentication only).

### GET`/v1/search/messages`

Full-text search messages. Messages of conversations of project steps are not searched.

#### Query Parameters

| パラメータ   | 型        | 必須 | 説明                                                            |
| ------- | -------- | -- | ------------------------------------------------------------- |
| `q`     | `string` | 必須 | Search query                                                  |
| `order` | `string` | —  | Sort order. "asc" (ascending) or "desc" (descending, default) |

#### Request Example

**Search messages**

**curl**

```curl
curl "https://<your-domain>/api/v1/search/messages?q=sales" \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests
from urllib.parse import quote

query = "sales"
response = requests.get(
  "https://<your-domain>/api/v1/search/messages",
  headers={"Authorization": f"Bearer {token}"},
  params={"q": query, "order": "desc"},
)

messages = response.json()["messages"]
for msg in messages:
  print(f"{msg['title']}: {msg['text'][:50]}")
```

**TypeScript**

```typescript
const query = "sales";
const params = new URLSearchParams({ q: query, order: "desc" });
const response = await fetch(
"https://<your-domain>/api/v1/search/messages?" + params,
{
  headers: { "Authorization": "Bearer " + accessToken },
}
);

const data = await response.json();
data.messages.forEach((msg) => {
console.log(msg.title + ": " + msg.text);
});
```

**Go**

```go
query := "sales"
req, _ := http.NewRequest("GET",
  fmt.Sprintf("https://<your-domain>/api/v1/search/messages?q=%s&order=desc",
      url.QueryEscape(query)),
  nil)
req.Header.Set("Authorization", "Bearer "+token)

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### Response Fields (200 OK)

| Field                                 | Type      | Description                                                                                                                                                                                                                                                  |
| ------------------------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `messages`                            | `array`   | Array of search result messages (up to 50)                                                                                                                                                                                                                   |
| `messages[].conversationId`           | `string`  | Conversation ID (UUID)                                                                                                                                                                                                                                       |
| `messages[].messageId`                | `string`  | Unique identifier of the message                                                                                                                                                                                                                             |
| `messages[].text`                     | `string`  | Message body text                                                                                                                                                                                                                                            |
| `messages[].title`                    | `string`  | Conversation title                                                                                                                                                                                                                                           |
| `messages[].sender`                   | `string`  | Sender. "User" or "AI"                                                                                                                                                                                                                                       |
| `messages[].createdAt`                | `string`  | Creation date and time (ISO 8601)                                                                                                                                                                                                                            |
| `messages[].updatedAt`                | `string`  | Last updated date and time (ISO 8601)                                                                                                                                                                                                                        |
| `messages[].matchedQueries`           | `array`   | Array of matched search queries                                                                                                                                                                                                                              |
| `messages[].status`                   | `object`  | Message processing status                                                                                                                                                                                                                                    |
| `messages[].status.processing`        | `boolean` | Whether the agent is currently processing                                                                                                                                                                                                                    |
| `messages[].status.unfinished`        | `boolean` | Whether the agent response was interrupted                                                                                                                                                                                                                   |
| `messages[].tasks`                    | `array`   | Array of tasks executed by the agent. See the Task object under [GET /v1/conversations/:conversationId/messages](#get-messages) for field definitions                                                                                                        |
| `messages[].deliverables`             | `array`   | Array of artifacts generated by the agent (included only when present)                                                                                                                                                                                       |
| `messages[].deliverables[].filename`  | `string`  | Artifact file name                                                                                                                                                                                                                                           |
| `messages[].deliverables[].filepath`  | `string`  | Artifact file path                                                                                                                                                                                                                                           |
| `messages[].deliverables[].source`    | `string`  | `"agent"` (agent-generated) or `"user"` (user-uploaded)                                                                                                                                                                                                      |
| `messages[].deliverables[].isPrimary` | `boolean` | Whether it is a primary artifact                                                                                                                                                                                                                             |
| `messages[].deliverables[].createdAt` | `string`  | Creation date and time (ISO 8601 format)                                                                                                                                                                                                                     |
| `messages[].deliverables[].mimeType`  | `string`  | MIME type (e.g., `"application/pdf"`, `"text/markdown"`). `"application/octet-stream"` when it cannot be determined                                                                                                                                          |
| `messages[].deliverables[].size`      | `number?` | File size (bytes). Omitted when 0 or below                                                                                                                                                                                                                   |
| `messages[].files`                    | `array?`  | Array of user-uploaded files. Included only when present for messages with `sender: "User"`. The field structure matches the history API (`fileId` / `mimeType` / `width?` / `height?`). See [GET /v1/conversations/:id/messages](#get-messages) for details |
| `hasMore`                             | `boolean` | true when more than 50 messages match (the newest 50 are returned, and the rest cannot be read; pagination not supported)                                                                                                                                    |

#### Response Example

```json
{
  "messages": [
    {
      "conversationId": "550e8400-...",
      "messageId": "msg-abc123",
      "text": "Result of sales data analysis...",
      "title": "Sales data analysis",
      "sender": "AI",
      "createdAt": "2026-03-14T10:30:00Z",
      "updatedAt": "2026-03-14T10:35:00Z",
      "matchedQueries": ["sales"],
      "tasks": []
    }
  ],
  "hasMore": false
}
```

#### Error Response

| Status | Description                                                                                                             |
| ------ | ----------------------------------------------------------------------------------------------------------------------- |
| `400`  | q parameter is missing or not a single string (for example, q specified more than once), or order is not "asc" / "desc" |

## User

Retrieve, update user information, and change password.

### Endpoint List

| メソッド  | エンドポイント             | 説明                      |
| ----- | ------------------- | ----------------------- |
| GET   | `/v1/user`          | Get user information    |
| PATCH | `/v1/user`          | Update user information |
| POST  | `/v1/user/password` | Change password         |

### GET`/v1/user`

Get user information.

#### Request Example

**Get user**

**curl**

```curl
curl https://<your-domain>/api/v1/user \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  "https://<your-domain>/api/v1/user",
  headers={"Authorization": f"Bearer {token}"},
)

user = response.json()
print(f"User: {user['username']} ({user['email']})")
```

**TypeScript**

```typescript
const response = await fetch(
"https://<your-domain>/api/v1/user",
{
  headers: { "Authorization": "Bearer " + accessToken },
}
);

const user = await response.json();
console.log("User: " + user.username + " (" + user.email + ")");
```

**Go**

```go
req, _ := http.NewRequest("GET",
  "https://<your-domain>/api/v1/user",
  nil)
req.Header.Set("Authorization", "Bearer "+token)

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var user map[string]interface{}
json.NewDecoder(resp.Body).Decode(&user)
fmt.Printf("User: %s (%s)\n", user["username"], user["email"])
```

#### Response Fields (200 OK)

| Field                | Type      | Description                                                     |
| -------------------- | --------- | --------------------------------------------------------------- |
| `userId`             | `string`  | Unique identifier of the user                                   |
| `email`              | `string`  | Email address                                                   |
| `username`           | `string`  | Username                                                        |
| `emailVerified`      | `boolean` | Email verification status                                       |
| `createdAt`          | `string`  | Account creation date and time (ISO 8601)                       |
| `isApproved`         | `boolean` | Account approval status                                         |
| `role`               | `string`  | User role                                                       |
| `organization`       | `object`  | Organization (included only when set)                           |
| `organization.value` | `string`  | Organization code                                               |
| `organization.label` | `string`  | Organization name                                               |
| `jobType`            | `object`  | Job type (included only when set)                               |
| `jobType.value`      | `string`  | Job type code                                                   |
| `jobType.label`      | `string`  | Job type name                                                   |
| `bio`                | `string`  | Bio (included only when set)                                    |
| `lastLoginAt`        | `string`  | Last login date and time (ISO 8601, included only when present) |

#### Response Example

```json
{
  "userId": "user-abc123",
  "email": "tanaka@example.com",
  "username": "John Doe",
  "emailVerified": true,
  "createdAt": "2026-03-10T09:00:00.000Z",
  "isApproved": true,
  "role": "user",
  "organization": { "value": "eng", "label": "Engineering Department" },
  "jobType": { "value": "dev", "label": "Developer" },
  "bio": "AI Engineer",
  "lastLoginAt": "2026-03-14T10:00:00.000Z"
}
```

### PATCH`/v1/user`

Update user information.

#### Request Body

| パラメータ          | 型        | 必須 | 説明                                                                                                                                                                             |
| -------------- | -------- | -- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `username`     | `string` | —  | Username                                                                                                                                                                       |
| `organization` | `string` | —  | Organization code. It can be set only while it is not set. Changing an organization that is already set (including clearing it) returns 403. Ask an administrator to change it |
| `jobType`      | `string` | —  | Job type code. It can be set only while it is not set. Changing a job type that is already set (including clearing it) returns 403. Ask an administrator to change it          |
| `bio`          | `string` | —  | Bio                                                                                                                                                                            |

#### Request Example

**Update user**

**curl**

```curl
curl -X PATCH https://<your-domain>/api/v1/user \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{ "username": "John Doe", "bio": "Engineering Department" }'
```

**Python**

```python
import requests

response = requests.patch(
  "https://<your-domain>/api/v1/user",
  headers={"Authorization": f"Bearer {token}"},
  json={"username": "John Doe", "bio": "Engineering Department"},
)

user = response.json()
print(f"Updated: {user['username']}")
```

**TypeScript**

```typescript
const response = await fetch(
"https://<your-domain>/api/v1/user",
{
  method: "PATCH",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    username: "John Doe",
    bio: "Engineering Department",
  }),
}
);

const user = await response.json();
console.log("Updated: " + user.username);
```

**Go**

```go
payload := map[string]string{
  "username": "John Doe",
  "bio": "Engineering Department",
}
body, _ := json.Marshal(payload)

req, _ := http.NewRequest("PATCH",
  "https://<your-domain>/api/v1/user",
  bytes.NewBuffer(body))
req.Header.Set("Authorization", "Bearer "+token)
req.Header.Set("Content-Type", "application/json")

resp, _ := http.DefaultClient.Do(req)
```

#### Response Fields (200 OK)

Returns the same user object as GET /v1/user (with updated values).

#### Response Example

```json
{
  "userId": "user-abc123",
  "email": "tanaka@example.com",
  "username": "John Doe",
  "emailVerified": true,
  "createdAt": "2026-03-10T09:00:00.000Z",
  "isApproved": true,
  "role": "user",
  "organization": { "value": "eng", "label": "Engineering Department" },
  "jobType": { "value": "dev", "label": "Developer" },
  "bio": "Engineering Department",
  "lastLoginAt": "2026-03-14T10:00:00.000Z"
}
```

#### Error Response

| Status | Description                                                                                                                                            |
| ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `400`  | No fields specified for update                                                                                                                         |
| `400`  | username / organization / jobType / bio is not a string, or the body is malformed JSON (`code: "invalid_body"`)                                        |
| `403`  | Tried to change an organization / jobType that is already set, including clearing it (`code: "affiliation_locked"`). Ask an administrator to change it |
| `409`  | Another update of the same user is in progress (`code: "conflict"`). Wait a moment and send the request again                                          |
| `415`  | The body Content-Type is not application/json (`code: "unsupported_media_type"`)                                                                       |

### POST`/v1/user/password`

Change password.

#### Request Body

| パラメータ             | 型        | 必須 | 説明                          |
| ----------------- | -------- | -- | --------------------------- |
| `currentPassword` | `string` | 必須 | Current password            |
| `newPassword`     | `string` | 必須 | New password                |
| `confirmPassword` | `string` | 必須 | New password (confirmation) |

#### Request Example

**Change password**

**curl**

```curl
curl -X POST https://<your-domain>/api/v1/user/password \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
  "currentPassword": "OldPass123!",
  "newPassword": "NewPass456!",
  "confirmPassword": "NewPass456!"
}'
```

**Python**

```python
import requests

response = requests.post(
  "https://<your-domain>/api/v1/user/password",
  headers={"Authorization": f"Bearer {token}"},
  json={
      "currentPassword": "OldPass123!",
      "newPassword": "NewPass456!",
      "confirmPassword": "NewPass456!",
  },
)

data = response.json()
print(f"Password changed: {data['changed']}")
```

**TypeScript**

```typescript
const response = await fetch(
"https://<your-domain>/api/v1/user/password",
{
  method: "POST",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    currentPassword: "OldPass123!",
    newPassword: "NewPass456!",
    confirmPassword: "NewPass456!",
  }),
}
);

const data = await response.json();
console.log("Password changed: " + data.changed);
```

**Go**

```go
payload := map[string]string{
  "currentPassword": "OldPass123!",
  "newPassword": "NewPass456!",
  "confirmPassword": "NewPass456!",
}
body, _ := json.Marshal(payload)

req, _ := http.NewRequest("POST",
  "https://<your-domain>/api/v1/user/password",
  bytes.NewBuffer(body))
req.Header.Set("Authorization", "Bearer "+token)
req.Header.Set("Content-Type", "application/json")

resp, _ := http.DefaultClient.Do(req)
```

#### Response Fields (200 OK)

| Field     | Type      | Description                               |
| --------- | --------- | ----------------------------------------- |
| `userId`  | `string`  | Unique identifier of the user             |
| `changed` | `boolean` | Always true on successful password change |

#### Response Example

```json
{ "userId": "user-abc123", "changed": true }
```

After you change the password, do not keep using the tokens obtained before the change; sign in again and get new tokens. An access token obtained before the change can still be used with the API until it expires.

#### Error Response

| Status | Description                                                                                                                                                                                                         |
| ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | Missing required parameters, currentPassword / newPassword / confirmPassword is not a string, the body is malformed JSON (`code: "invalid_body"`), password validation failed, or the current password is incorrect |
| `415`  | The body Content-Type is not application/json (`code: "unsupported_media_type"`)                                                                                                                                    |
| `401`  | Authentication token is invalid                                                                                                                                                                                     |

## Master Data

Retrieve master data such as organizations and job types.

### Endpoint List

| メソッド | エンドポイント             | 説明                 |
| ---- | ------------------- | ------------------ |
| GET  | `/v1/organizations` | List organizations |
| GET  | `/v1/job-types`     | List job types     |

### GET`/v1/organizations`

List organizations. Inactive organizations are not included.

#### Request Example

**List organizations**

**curl**

```curl
curl https://<your-domain>/api/v1/organizations \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  "https://<your-domain>/api/v1/organizations",
  headers={"Authorization": f"Bearer {token}"},
)

data = response.json()
for org in data["organizations"]:
  print(f"{org['value']}: {org['label']}")
```

**TypeScript**

```typescript
const response = await fetch(
"https://<your-domain>/api/v1/organizations",
{
  headers: { "Authorization": "Bearer " + accessToken },
}
);

const data = await response.json();
data.organizations.forEach((org) => {
console.log(org.value + ": " + org.label);
});
```

**Go**

```go
req, _ := http.NewRequest("GET",
  "https://<your-domain>/api/v1/organizations",
  nil)
req.Header.Set("Authorization", "Bearer "+token)

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### Response Fields (200 OK)

| Field                   | Type      | Description                             |
| ----------------------- | --------- | --------------------------------------- |
| `organizations`         | `array`   | Array of organization objects           |
| `organizations[].value` | `string`  | Organization code                       |
| `organizations[].label` | `string`  | Organization name                       |
| `hasMore`               | `boolean` | Always false (pagination not supported) |

#### Response Example

```json
{
  "organizations": [
    { "value": "eng", "label": "Engineering Department" },
    { "value": "sales", "label": "Sales Department" }
  ],
  "hasMore": false
}
```

### GET`/v1/job-types`

List job types. Inactive job types are not included.

#### Request Example

**List job types**

**curl**

```curl
curl https://<your-domain>/api/v1/job-types \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  "https://<your-domain>/api/v1/job-types",
  headers={"Authorization": f"Bearer {token}"},
)

job_types = response.json()["jobTypes"]
for jt in job_types:
  print(f"{jt['value']}: {jt['label']}")
```

**TypeScript**

```typescript
const response = await fetch(
"https://<your-domain>/api/v1/job-types",
{
  headers: { "Authorization": "Bearer " + accessToken },
}
);

const data = await response.json();
data.jobTypes.forEach((jt) => {
console.log(jt.value + ": " + jt.label);
});
```

**Go**

```go
req, _ := http.NewRequest("GET",
  "https://<your-domain>/api/v1/job-types",
  nil)
req.Header.Set("Authorization", "Bearer "+token)

resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

var result map[string]interface{}
json.NewDecoder(resp.Body).Decode(&result)
fmt.Println(result)
```

#### Response Fields (200 OK)

| Field              | Type      | Description                             |
| ------------------ | --------- | --------------------------------------- |
| `jobTypes`         | `array`   | Array of job type objects               |
| `jobTypes[].value` | `string`  | Job type code                           |
| `jobTypes[].label` | `string`  | Job type name                           |
| `hasMore`          | `boolean` | Always false (pagination not supported) |

#### Response Example

```json
{
  "jobTypes": [
    { "value": "dev", "label": "Developer" },
    { "value": "pm", "label": "Project Manager" }
  ],
  "hasMore": false
}
```

<!-- -->

## Projects

The project APIs are in the [User API Reference (Projects)](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/marketplace/api/reference/user-api-reference-projects.md).

## Error Responses

### HTTP Status Codes

HTTP status codes that may be returned by all endpoints.

| Status                       | Description                                                                                                                                                                                                                                                           |
| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400 Bad Request`            | Invalid request parameters                                                                                                                                                                                                                                            |
| `401 Unauthorized`           | Token is invalid or missing                                                                                                                                                                                                                                           |
| `403 Forbidden`              | No access permission to the resource                                                                                                                                                                                                                                  |
| `404 Not Found`              | Resource does not exist, or the path or method is not defined (405 is not returned)                                                                                                                                                                                   |
| `409 Conflict`               | Operation conflict, such as the resource currently being processed                                                                                                                                                                                                    |
| `413 Payload Too Large`      | Request body exceeds the size limit                                                                                                                                                                                                                                   |
| `415 Unsupported Media Type` | The request body format (Content-Type) is not supported                                                                                                                                                                                                               |
| `429 Too Many Requests`      | Rate limit or concurrent-run limit exceeded. `error.type` is `rate_limit_error`, and `error.code` depends on the endpoint (for example `monthly_quota_exceeded` for the monthly limit and `too_many_active_runs` for concurrent project runs). Please wait and retry. |
| `500 Internal Server Error`  | Internal server error                                                                                                                                                                                                                                                 |
| `502 Bad Gateway`            | Communication error with upstream services (authentication / chat backends, etc.)                                                                                                                                                                                     |
| `503 Service Unavailable`    | Service temporarily unavailable                                                                                                                                                                                                                                       |
| `504 Gateway Timeout`        | Upstream service response timeout                                                                                                                                                                                                                                     |

### Error Response Format

All error responses are returned in the following common structure.

| Field                    | Type     | Description                                                                                                                                                                                                                                                        |
| ------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `error.type`             | `string` | Error classification. One of: "invalid\_request\_error", "authentication\_error", "insufficient\_scope\_error", "forbidden\_error", "not\_found\_error", "conflict\_error", "payload\_too\_large\_error", "rate\_limit\_error", "server\_error", "upstream\_error" |
| `error.message`          | `string` | Human-readable error message                                                                                                                                                                                                                                       |
| `error.code`             | `string` | Machine-processable error code (e.g., "missing\_parameter", "invalid\_parameter", "invalid\_token")                                                                                                                                                                |
| `error.param`            | `string` | The parameter that caused the error. Included only for validation errors                                                                                                                                                                                           |
| `error.suggested_action` | `string` | Recommended action to take. Included only for some errors                                                                                                                                                                                                          |

```json
{
  "error": {
    "type": "invalid_request_error",
    "message": "Invalid parameter: limit",
    "code": "invalid_parameter",
    "param": "limit",
    "suggested_action": "limit must be between 1 and 100"
  }
}
```
