# System Integration API Reference

API reference for user management, log viewing, master data management, shared memory search, and project operations. For end-user-facing APIs (Chat / Conversations / Files / Search / public master data), see the [User API Reference](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/reference/api-reference.md). For MCP / A2A connection methods, see the [Connection Methods Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/guide/connection-guide.md).

> **SaaS Edition Only**
>
> All endpoints documented in this reference are **available only in the SaaS edition**. On the Marketplace edition, administrative operations are performed exclusively through the admin console.

## Base URL

All API requests are sent to the following base URL.

SaaS

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

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

## Authentication

All API requests require a Bearer token in the `Authorization` header.

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

If the token is invalid or missing, `401 Unauthorized` is returned. Some endpoints require additional scopes. If the required scope is missing, `403 Forbidden` is returned.

For details on obtaining tokens and scope assignment, see the [Authentication Guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/guide/auth-guide.md) and [Authentication API Reference (SaaS)](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/reference/auth-saas-ref.md).

## Common Rules

These rules apply to the APIs on this page.

### How requests are handled

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

| What you sent                                                                                                                                             | How it is handled                                                                                                                                |
| --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| Query parameters and body fields not in the specification                                                                                                 | Ignored. However, even items not listed on this page may return `400 Bad Request` if their type or value is wrong, when the service accepts them |
| An invalid value for a query parameter in the specification                                                                                               | `400 Bad Request`                                                                                                                                |
| An invalid URL encoding in a path parameter value (a `%` sequence)                                                                                        | `400 Bad Request` (`invalid_parameter`)                                                                                                          |
| A malformed JSON body                                                                                                                                     | `400 Bad Request` (`invalid_body`)                                                                                                               |
| A body other than `Content-Type: application/json`, or a body with an unsupported character set (`charset`), sent to an endpoint that accepts a JSON body | `415 Unsupported Media Type` (`unsupported_media_type`)                                                                                          |
| A body field of the wrong type                                                                                                                            | `400 Bad Request`                                                                                                                                |

If reading the body results in `400` (malformed JSON and so on) or `413` (the size limit was exceeded and so on), that is returned before `415`.

Responses carry an `x-request-id` header. The service assigns this value; a value you send in the request is not used. Please tell us this value when you contact us.

### Pagination

List retrieval endpoints use one of two schemes. Which one applies is fixed per endpoint. [Organization and job type](#admin-master-data) lists do not support pagination and always return all records.

#### Page-based

| Parameter | Type      | Description                                     |
| --------- | --------- | ----------------------------------------------- |
| `limit`   | `integer` | Number of items per page. 1 to 100 (default 25) |
| `page`    | `integer` | Page number. 1 or greater (default 1)           |

Responses include `total`, `limit`, `page`, and `hasMore`. When `hasMore` is `true`, increase `page` by 1 to retrieve the next page.

```bash
# Page 1
curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users?limit=25&page=1" \
  -H "Authorization: Bearer <access_token>"

# Page 2
curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users?limit=25&page=2" \
  -H "Authorization: Bearer <access_token>"
```

Endpoints using this scheme: the [users list](#admin-users) and the [log lists](#admin-logs) (audit logs, operation audit logs, LLM logs, LLM Gateway logs, LLM Gateway operation audit, access logs, and guardrail alerts).

#### Cursor-based

| Parameter | Type      | Description                                                                           |
| --------- | --------- | ------------------------------------------------------------------------------------- |
| `limit`   | `integer` | Number of items per page (1-100). Defaults to 50                                      |
| `cursor`  | `string`  | Cursor value for the next page. Pass back the cursor from the previous response as-is |

Responses include `hasMore`. When it is `true`, pass the `cursor` value in the next request to retrieve the next page. Treat `cursor` as opaque: do not interpret it, just pass the previous value back.

Endpoints using this scheme: the [project list](#projects) and the [user action audit list](#get-admin-user-action-logs). They do not use `page` (it is ignored if specified).

## Shared Memory SaaS

Searches shared memory (knowledge) based on organization and job role.

### Endpoint List

| メソッド | エンドポイント                  | 説明                   | スコープ                 |
| ---- | ------------------------ | -------------------- | -------------------- |
| POST | `/v1/admin/memory/query` | Search shared memory | `sharedmemory:query` |

### POST`/v1/admin/memory/query`

Search shared memory.

#### Request Body

| パラメータ     | 型        | 必須 | 説明                                                                                                       |
| --------- | -------- | -- | -------------------------------------------------------------------------------------------------------- |
| `query`   | `string` | 必須 | Search query (max 500 characters)                                                                        |
| `orgId`   | `string` | —  | Organization ID (max 100 characters). If specified, organization-scoped memory is included in the search |
| `jobRole` | `string` | —  | Job role (max 100 characters). If specified, role-scoped memory is included in the search                |

#### Request Example

**Search shared memory**

**curl**

```curl
curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/memory/query \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{"query": "How to create a sales report", "orgId": "sales"}'
```

**Python**

```python
import requests

response = requests.post(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/memory/query",
  headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"},
  json={"query": "How to create a sales report", "orgId": "sales"},
)

response.raise_for_status()  # 502 / 504 are transient failures. Retry after a delay.
data = response.json()
for memory in data.get("memories", []):
  print(f"[{memory['type']}] {memory['text']}")
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/memory/query",
{
  method: "POST",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ query: "How to create a sales report", orgId: "sales" }),
}
);

if (!response.ok) {
// 502 / 504 are transient failures. Retry after a delay.
throw new Error(`memory query failed: ${response.status}`);
}

const data = await response.json();
(data.memories ?? []).forEach((m) => {
console.log(`[${m.type}] ${m.text}`);
});
```

**Go**

```go
body, _ := json.Marshal(map[string]string{
  "query": "How to create a sales report",
  "orgId": "sales",
})
req, _ := http.NewRequest("POST",
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/memory/query",
  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()

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

#### Response Fields (200 OK)

| Field                  | Type             | Description                                                   |
| ---------------------- | ---------------- | ------------------------------------------------------------- |
| `memories`             | `array`          | Array of memory objects                                       |
| `memories[].text`      | `string`         | Memory content text                                           |
| `memories[].type`      | `string`         | "knowledge"                                                   |
| `memories[].scope`     | `string`         | One of "organization", "role", or "global"                    |
| `memories[].createdAt` | `string \| null` | Creation date and time (ISO 8601)                             |
| `memories[].score`     | `number?`        | Relevance score. Field is omitted when score is not available |

#### Response Headers

| Header                  | Description                                |
| ----------------------- | ------------------------------------------ |
| `X-RateLimit-Limit`     | Monthly request limit                      |
| `X-RateLimit-Remaining` | Remaining requests                         |
| `X-RateLimit-Reset`     | Reset time (start of next month, ISO 8601) |

#### Response Example

```json
{
  "memories": [
    {
      "text": "Sales reports can be created from the 'Monthly Reports' tab in the dashboard",
      "type": "knowledge",
      "scope": "organization",
      "createdAt": "2026-03-15T10:30:00.000Z",
      "score": 0.85
    }
  ]
}
```

#### Error Response

| Status | Description                                                                                                |
| ------ | ---------------------------------------------------------------------------------------------------------- |
| `400`  | query is missing, empty, or exceeds 500 characters, or the body is malformed JSON (`code: "invalid_body"`) |
| `415`  | The body Content-Type is not application/json (`code: "unsupported_media_type"`)                           |
| `403`  | sharedmemory:query scope is missing                                                                        |
| `429`  | Monthly quota exceeded (`error.type: rate_limit_error`, `error.code: monthly_quota_exceeded`)              |
| `502`  | Communication error with an upstream service (`error.type: upstream_error`)                                |
| `504`  | Upstream service response timeout (`error.type: upstream_error`, `error.code: upstream_timeout`)           |

When the search succeeds with no matches, `200` is returned with an empty `memories` array. Upstream failures return `502` / `504` instead of an empty array, so an empty array in a `200` response does not indicate a failure.

## User Management SaaS

List, create, delete, change role, approve, revoke approval, suspend and resume, unlock, and change the affiliation and job of users.

### Endpoint List

| メソッド   | エンドポイント                               | 説明                                  | スコープ                        |
| ------ | ------------------------------------- | ----------------------------------- | --------------------------- |
| GET    | `/v1/admin/users`                     | List users                          | `users:read / users:manage` |
| GET    | `/v1/admin/users/:userId/passkeys`    | Get the passkeys of a user          | `users:read / users:manage` |
| POST   | `/v1/admin/users`                     | Create a user                       | `users:manage`              |
| DELETE | `/v1/admin/users/:userId`             | Delete user                         | `users:manage`              |
| PUT    | `/v1/admin/users/:userId/role`        | Change user role                    | `users:manage`              |
| POST   | `/v1/admin/users/:userId/approve`     | Approve user                        | `users:manage`              |
| POST   | `/v1/admin/users/:userId/reject`      | Revoke user approval                | `users:manage`              |
| POST   | `/v1/admin/users/:userId/suspend`     | Suspend a user                      | `users:manage`              |
| POST   | `/v1/admin/users/:userId/resume`      | Resume a suspended user             | `users:manage`              |
| POST   | `/v1/admin/users/:userId/unlock`      | Unlock a user                       | `users:manage`              |
| PUT    | `/v1/admin/users/:userId/affiliation` | Change a user's affiliation and job | `users:manage`              |

### GET`/v1/admin/users`

List users. Supports page-based pagination. Either the `users:read` or `users:manage` scope is required (`users:manage` includes `users:read` permissions).

#### Query Parameters

| パラメータ          | 型         | 必須 | 説明                                                                                                                      |
| -------------- | --------- | -- | ----------------------------------------------------------------------------------------------------------------------- |
| `limit`        | `integer` | —  | Number of items to fetch (1–100, default: 25)                                                                           |
| `page`         | `integer` | —  | Page number (1 or more, default: 1)                                                                                     |
| `role`         | `string`  | —  | Role filter: "admin" (administrators only) or "user" (users other than administrators)                                  |
| `is_approved`  | `string`  | —  | Approval status filter. "true" or "false". Suspended users are included in true                                         |
| `search`       | `string`  | —  | Search string (max 100 characters). Searches by email address, etc.                                                     |
| `organization` | `string`  | —  | Organization code filter (exact match on the code, case-sensitive; max 50 characters; alphanumeric, hyphen, underscore) |
| `job_type`     | `string`  | —  | Job type code filter (exact match on the code, case-sensitive; max 50 characters; alphanumeric, hyphen, underscore)     |
| `order`        | `string`  | —  | Sort order: "asc" or "desc" (default: "desc"), by registration time. Other values return 400                            |

#### Request Example

**List users**

**curl**

```curl
curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users?limit=10&is_approved=true" \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users",
  headers={"Authorization": f"Bearer {token}"},
  params={"limit": 10, "is_approved": "true"},
)

data = response.json()
for user in data["users"]:
  print(f"{user['email']} ({user['role']}, {user['status']})")
```

**TypeScript**

```typescript
const params = new URLSearchParams({ limit: "10", is_approved: "true" });
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users?" + params,
{
  headers: { "Authorization": "Bearer " + accessToken },
}
);

const data = await response.json();
data.users.forEach((user) => {
console.log(user.email + " (" + user.role + ", " + user.status + ")");
});
```

**Go**

```go
req, _ := http.NewRequest("GET",
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users?limit=10&is_approved=true",
  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                                                                                                                                                                                                                           |
| ----------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `users`                 | `array`   | Array of user objects                                                                                                                                                                                                                 |
| `users[].userId`        | `string`  | User ID                                                                                                                                                                                                                               |
| `users[].email`         | `string`  | Email address                                                                                                                                                                                                                         |
| `users[].username`      | `string`  | Username                                                                                                                                                                                                                              |
| `users[].emailVerified` | `boolean` | Email verification status                                                                                                                                                                                                             |
| `users[].role`          | `string`  | Role ("admin" or "user")                                                                                                                                                                                                              |
| `users[].status`        | `string`  | Status ("unverified", "pending", "approved", or "suspended"). "suspended" is an approved user whose use was suspended in the admin console (cannot sign in)                                                                           |
| `users[].organization`  | `object?` | Organization (value: code, label: name). Field is omitted if not set                                                                                                                                                                  |
| `users[].jobType`       | `object?` | Job type (value: code, label: name). Field is omitted if not set                                                                                                                                                                      |
| `users[].bio`           | `string?` | Self-introduction. Field is omitted when not set                                                                                                                                                                                      |
| `users[].createdAt`     | `string`  | Creation date and time (ISO 8601)                                                                                                                                                                                                     |
| `users[].lastLoginAt`   | `string?` | Last login date and time (ISO 8601). Field is omitted if the user has never logged in                                                                                                                                                 |
| `users[].idpSynced`     | `boolean` | Whether the user is synced from the identity provider (IdP). For a user with true, an organization or job type that is already set cannot be changed with PUT /v1/admin/users/:userId/affiliation (409 affiliation\_managed\_by\_idp) |
| `total`                 | `integer` | Total count                                                                                                                                                                                                                           |
| `limit`                 | `integer` | Number of items fetched                                                                                                                                                                                                               |
| `page`                  | `integer` | Page number                                                                                                                                                                                                                           |
| `hasMore`               | `boolean` | Whether the next page exists                                                                                                                                                                                                          |

##### Example Response (200 OK)

```json
{
  "users": [
    {
      "userId": "bbbe4306-6975-420b-af47-fb4c8f48b4aa",
      "email": "user1@example.com",
      "username": "user1@example.com",
      "emailVerified": true,
      "role": "user",
      "status": "approved",
      "createdAt": "2026-04-19T13:02:26.198Z",
      "idpSynced": false
    },
    {
      "userId": "90b40fd8-a6b8-42b8-ab61-f3b674169b43",
      "email": "user2@example.com",
      "username": "user2",
      "emailVerified": true,
      "role": "user",
      "status": "approved",
      "organization": { "value": "sales", "label": "Sales" },
      "jobType": { "value": "engineer", "label": "Engineer" },
      "createdAt": "2026-04-17T07:09:47.484Z",
      "idpSynced": true
    },
    {
      "userId": "463e2c25-5a80-4362-b77e-941df96fb1f2",
      "email": "admin@example.com",
      "username": "admin@example.com",
      "emailVerified": true,
      "role": "admin",
      "status": "approved",
      "createdAt": "2026-04-17T07:02:41.015Z",
      "lastLoginAt": "2026-04-17T07:18:17.488Z",
      "idpSynced": false
    }
  ],
  "total": 132,
  "limit": 3,
  "page": 1,
  "hasMore": true
}
```

#### Error Response

| Status | Description                                 |
| ------ | ------------------------------------------- |
| `400`  | Invalid query parameters                    |
| `403`  | users:read or users:manage scope is missing |

### GET`/v1/admin/users/:userId/passkeys`

Get the list of passkeys registered by a user. Requires either the `users:read` or `users:manage` scope. Passkeys are deleted in the admin console (this API cannot delete them).

#### Path Parameters

| パラメータ    | 型        | 必須 | 説明      |
| -------- | -------- | -- | ------- |
| `userId` | `string` | 必須 | User ID |

#### Request Example

**List user passkeys**

**curl**

```curl
curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/bbbe4306-6975-420b-af47-fb4c8f48b4aa/passkeys \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/bbbe4306-6975-420b-af47-fb4c8f48b4aa/passkeys",
  headers={"Authorization": f"Bearer {token}"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/bbbe4306-6975-420b-af47-fb4c8f48b4aa/passkeys",
{
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

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

**Go**

```go
req, _ := http.NewRequest("GET", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/bbbe4306-6975-420b-af47-fb4c8f48b4aa/passkeys", 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

| Field                     | Type             | Description                                                    |
| ------------------------- | ---------------- | -------------------------------------------------------------- |
| `passkeys`                | `array`          | Array of passkeys (all of them)                                |
| `passkeys[].credentialId` | `string`         | ID of the passkey                                              |
| `passkeys[].label`        | `string \| null` | Name of the passkey                                            |
| `passkeys[].createdAt`    | `string \| null` | When it was registered (ISO 8601)                              |
| `passkeys[].lastUsedAt`   | `string \| null` | When it was last used (ISO 8601). null if it has not been used |
| `hasMore`                 | `boolean`        | Always false (all of them are returned)                        |

##### Example Response (200 OK)

```json
{
  "passkeys": [
    {
      "credentialId": "AbCdEf0123456789_-AbCdEf0123456789_-AbCdEf0",
      "label": "Work PC",
      "createdAt": "2026-10-01T02:30:00.000Z",
      "lastUsedAt": "2026-11-17T23:45:10.000Z"
    }
  ],
  "hasMore": false
}
```

#### Error Responses

| Status | Description                              |
| ------ | ---------------------------------------- |
| `403`  | Missing users:read or users:manage scope |
| `404`  | User not found                           |

### POST`/v1/admin/users`

Creates one user. Requires the `users:manage` scope. The created user is approved (`status` is `"approved"`) and counts toward the contracted number of users.

- If you do not send `password`, a temporary password is generated and returned once, as `temporaryPassword`, in the response to the creation. It cannot be read later, so pass it on to the user. This response has `Cache-Control: no-store`.
- The notification email (`sendNotificationEmail`) does not contain the password.
- Creating users with the same email address at the same time, or creating users at the same time when one more user is left within the contracted number, can give 500 or create users beyond the limit. Create users one after another.

#### Request Body

| パラメータ                   | 型         | 必須 | 説明                                                                                                                                                                     |
| ----------------------- | --------- | -- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `email`                 | `string`  | 必須 | Email address. Leading and trailing whitespace is removed and it is lowercased (up to 255 characters)                                                                  |
| `displayName`           | `string`  | 必須 | Display name (up to 255 characters). Leading and trailing whitespace is removed, and < and > are removed                                                               |
| `role`                  | `string`  | 必須 | "admin" or "user"                                                                                                                                                      |
| `organization`          | `string`  | 必須 | Organization code (a value from GET /v1/organizations)                                                                                                                 |
| `job`                   | `string`  | 必須 | Job type code (a value from GET /v1/job-types)                                                                                                                         |
| `bio`                   | `string`  | —  | Bio (up to 255 characters). Leading and trailing whitespace is removed, and < and > are removed                                                                        |
| `password`              | `string`  | —  | The first password. 400 if it does not meet the password rules. If omitted, a temporary password is generated and returned in temporaryPassword of the response        |
| `temporary`             | `boolean` | —  | Whether the user must change the password at the first sign-in. If omitted, true when password is not sent, and false when it is sent                                  |
| `sendNotificationEmail` | `boolean` | —  | Whether to notify the user of the creation by email. If omitted, true. In an environment that cannot send email, it is not sent and emailSent in the response is false |

#### Request Example

**Create user**

**curl**

```curl
curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{"email": "new.user@example.com", "displayName": "New User", "role": "user", "organization": "ORG001", "job": "JOB01"}'
```

**Python**

```python
import requests

response = requests.post(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users",
  headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"},
  json={
      "email": "new.user@example.com",
      "displayName": "New User",
      "role": "user",
      "organization": "ORG001",
      "job": "JOB01",
  },
)
```

**TypeScript**

```typescript
const response = await fetch("https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users", {
method: "POST",
headers: {
  "Authorization": "Bearer " + accessToken,
  "Content-Type": "application/json",
},
body: JSON.stringify({
  email: "new.user@example.com",
  displayName: "New User",
  role: "user",
  organization: "ORG001",
  job: "JOB01",
}),
});
```

**Go**

```go
body, _ := json.Marshal(map[string]string{
  "email":        "new.user@example.com",
  "displayName":  "New User",
  "role":         "user",
  "organization": "ORG001",
  "job":          "JOB01",
})
req, _ := http.NewRequest("POST",
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users",
  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()
```

#### Response Fields (201 Created)

| Field               | Type      | Description                                                                                                |
| ------------------- | --------- | ---------------------------------------------------------------------------------------------------------- |
| `user`              | `object`  | The created user. The same fields as users\[] in List Users (status is "approved", and idpSynced is false) |
| `emailSent`         | `boolean` | Whether the notification email was sent                                                                    |
| `temporaryPassword` | `string?` | Only when password was not sent. The generated temporary password (returned only once, in this response)   |

##### Response Example (201 Created)

```json
{
  "user": {
    "userId": "5d1c9b2e-8f4a-4c3b-9e7d-1a2b3c4d5e6f",
    "email": "new.user@example.com",
    "username": "new.user@example.com",
    "emailVerified": true,
    "role": "user",
    "status": "approved",
    "organization": { "value": "ORG001", "label": "Sales" },
    "jobType": { "value": "JOB01", "label": "Engineer" },
    "createdAt": "2026-11-10T09:00:00.000Z",
    "idpSynced": false
  },
  "emailSent": true,
  "temporaryPassword": "<temporary password>"
}
```

#### Error Responses

| Status          | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`           | email, displayName, role, organization, or job is missing; any of them or bio is not a string, empty, or only whitespace (for displayName, organization, job, and bio, also a value that is only whitespace after < and > are removed); role is not "admin" or "user"; displayName or bio is longer than 255 characters; password is empty or only whitespace; temporary or sendNotificationEmail is not a boolean; the email address is malformed; an organization or job type code is wrong; or the password does not meet the rules (`code: "invalid_parameter"`) |
| `400`           | The body is malformed JSON or not a JSON object (`code: "invalid_body"`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `415`           | The body Content-Type is not application/json (`code: "unsupported_media_type"`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `401`           | The token is invalid or missing (`code: "invalid_token"`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `403`           | Missing users:manage scope (`code: "insufficient_scope"`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `409`           | A user with the same email address exists (`code: "user_exists"`; `param` is `email`). Use a different email address                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `409`           | The contracted number of users has been reached (`code: "conflict"`)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `429`           | The limit on requests per source IP address (30 per hour) was exceeded (`code: "rate_limit_exceeded"`). Wait a moment and send it again                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `500, 502, 504` | The user may have been created. Check with `GET /v1/admin/users?search=<email>` before sending again (if it was created, sending again gives 409 `user_exists`). If it was created and you did not receive the temporary password, the user sets one from "Forgot password?" on the sign-in screen. In an environment that cannot send email, set the password again in the admin console                                                                                                                                                                            |
| `503`           | The contracted number of users cannot be checked. Wait a moment and send it again                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |

### DELETE`/v1/admin/users/:userId`

Delete a user. A deleted user disappears from the admin console, the chat screens and the API, and this cannot be undone. To have the user's archived conversations, per-conversation work notes and per-user settings records deleted as well, see the [administrator guide](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/admin/guide/login-sso-guide.md#stopping-and-restoring-users). Requires `users:manage` scope. Access tokens issued to the user before the deletion may remain usable until they expire (the `expires_in` returned when they were obtained).

#### Path Parameters

| パラメータ    | 型        | 必須 | 説明      |
| -------- | -------- | -- | ------- |
| `userId` | `string` | 必須 | User ID |

#### Request Example

**Delete user**

**curl**

```curl
curl -X DELETE https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/USER_ID \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.delete(
  f"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/{user_id}",
  headers={"Authorization": f"Bearer {token}"},
)
```

**TypeScript**

```typescript
const response = await fetch(
`https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/${userId}`,
{
  method: "DELETE",
  headers: { "Authorization": "Bearer " + accessToken },
}
);
```

**Go**

```go
req, _ := http.NewRequest("DELETE",
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/"+userID,
  nil)
req.Header.Set("Authorization", "Bearer "+token)

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

##### Response Example (200 OK)

```json
{ "userId": "abc123", "deleted": true }
```

#### Error Responses

| Status | Description                                                                                                                                     |
| ------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `403`  | Missing users:manage scope                                                                                                                      |
| `404`  | The specified user was not found (including already deleted)                                                                                    |
| `429`  | The limit on requests per source IP address (10 per minute) was exceeded (`code: "rate_limit_exceeded"`). Wait a moment and send it again       |
| `500`  | Some of the user's data could not be deleted, so the deletion was stopped (`code: "user_delete_incomplete"`). The user is kept. Delete it again |

### PUT`/v1/admin/users/:userId/role`

Change a user's role. Only users with status "approved", and "suspended" users whose `emailVerified` is true, can have their role changed.

> **Behavior on Role Change**
>
> - **When demoting to `user`**: The target user's existing sessions are not ended automatically. The permissions in access tokens that were already issued do not change until they expire.
> - **When promoting to `admin`**: The target user's existing sessions continue, and the new permissions take effect in tokens issued after the promotion.

#### Path Parameters

| パラメータ    | 型        | 必須 | 説明      |
| -------- | -------- | -- | ------- |
| `userId` | `string` | 必須 | User ID |

#### Request Body

| パラメータ  | 型        | 必須 | 説明                                       |
| ------ | -------- | -- | ---------------------------------------- |
| `role` | `string` | 必須 | The role to change to. "admin" or "user" |

#### Request Example

**Change user role**

**curl**

```curl
curl -X PUT https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/USER_ID/role \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{"role": "admin"}'
```

**Python**

```python
import requests

response = requests.put(
  f"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/{user_id}/role",
  headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"},
  json={"role": "admin"},
)
```

**TypeScript**

```typescript
const response = await fetch(
`https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/${userId}/role`,
{
  method: "PUT",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ role: "admin" }),
}
);
```

**Go**

```go
body, _ := json.Marshal(map[string]string{"role": "admin"})
req, _ := http.NewRequest("PUT",
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/"+userID+"/role",
  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()
```

##### Response Example (200 OK)

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

#### Error Response

| Status | Description                                                                                                                                                                    |
| ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `400`  | role is missing or invalid, the body is malformed JSON (`code: "invalid_body"`), or the target user is neither "approved" nor a "suspended" user whose `emailVerified` is true |
| `415`  | The body Content-Type is not application/json (`code: "unsupported_media_type"`)                                                                                               |
| `403`  | users:manage scope is missing                                                                                                                                                  |
| `404`  | User not found                                                                                                                                                                 |
| `409`  | Another update of the same user (approval, role change, profile update, and so on) is in progress (`code: "conflict"`). Wait a moment and send it again                        |
| `429`  | The limit on requests per source IP address (100 per minute) was exceeded (`code: "rate_limit_exceeded"`). Wait a moment and send it again                                     |
| `500`  | The role change could not be finished (`code: "internal_error"`). Get the user again to check the current role, and send the same change again if needed                       |

### POST`/v1/admin/users/:userId/approve`

Approve a user. Only users with status "pending" can be approved. A user whose approval was revoked (stopped) is also shown as "pending" and can be approved; approving lets the user sign in again and the data is still there, but what the revocation stopped (running conversations, personal schedules, and the patrols and runs of projects the user owns) and the deleted connections to external services are not restored automatically.

> **note**
>
> When approval succeeds, an approval notification email is automatically sent to the target user's email address.

#### Path Parameters

| パラメータ    | 型        | 必須 | 説明      |
| -------- | -------- | -- | ------- |
| `userId` | `string` | 必須 | User ID |

#### Request Body (optional)

| パラメータ    | 型        | 必須 | 説明                                                                                  |
| -------- | -------- | -- | ----------------------------------------------------------------------------------- |
| `reason` | `string` | —  | Reason for the approval. If it is not empty, it is recorded in the user information |

#### Request Example

**Approve user**

**curl**

```curl
curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/USER_ID/approve \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{}'
```

**Python**

```python
import requests

response = requests.post(
  f"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/{user_id}/approve",
  headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"},
  json={},
)
```

**TypeScript**

```typescript
const response = await fetch(
`https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/${userId}/approve`,
{
  method: "POST",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Content-Type": "application/json",
  },
  body: "{}",
}
);
```

**Go**

```go
req, _ := http.NewRequest("POST",
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/"+userID+"/approve",
  strings.NewReader("{}"))
req.Header.Set("Authorization", "Bearer "+token)
req.Header.Set("Content-Type", "application/json")

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

##### Response Example (200 OK)

```json
{ "userId": "abc123", "approved": true }
```

#### Error Responses

| Status | Description                                                                                                                                                                                            |
| ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `400`  | User status is not "pending" (cannot approve: the email address has not been verified, or the user is already approved, including suspended users)                                                     |
| `400`  | reason is not a string, or the body is malformed JSON or not a JSON object (`code: "invalid_body"`)                                                                                                    |
| `415`  | The body Content-Type is not application/json (`code: "unsupported_media_type"`)                                                                                                                       |
| `403`  | Missing users:manage scope                                                                                                                                                                             |
| `404`  | User not found                                                                                                                                                                                         |
| `429`  | The limit on requests per source IP address (10 per minute) was exceeded (`code: "rate_limit_exceeded"`). Wait a moment and send it again                                                              |
| `409`  | After you got the user, it was approved by another operation, the contracted number of users was reached, or another update of the same user is in progress (`code: "conflict"`)                       |
| `500`  | The approval was not applied, because the change could not be passed to the chat; the user is not approved yet (`code: "user_suspension_incomplete"`). Send the same request again; it can be repeated |

### POST`/v1/admin/users/:userId/reject`

Revoke a user's approval. Only users with status "approved", and "suspended" users whose `emailVerified` is true, can have their approval revoked (a user whose approval was already revoked can be revoked again; it is a retry). Revoking disables the user, who can no longer sign in, and removes the user from the contracted number of accounts. Conversations, files, schedules and other data are kept. Revoking stops the same things as suspending (`/suspend`): running conversations and personal schedules, the patrols and open runs of projects the user owns, and the user's connections to external services are deleted. Approving the user again (`approve`) does not restore them automatically. Suspending (`/suspend`) keeps the user counted in the number of accounts; revoking removes the user from it. After revocation, the status is shown as "pending". Access tokens issued to the user before the revocation may remain usable until they expire (the `expires_in` returned when they were obtained).

> **note**
>
> A notification email is automatically sent to the target user's email address once, when an approved user is revoked.

#### Path Parameters

| パラメータ    | 型        | 必須 | 説明      |
| -------- | -------- | -- | ------- |
| `userId` | `string` | 必須 | User ID |

#### Request Example

**Reject user**

**curl**

```curl
curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/USER_ID/reject \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{}'
```

**Python**

```python
import requests

response = requests.post(
  f"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/{user_id}/reject",
  headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"},
  json={},
)
```

**TypeScript**

```typescript
const response = await fetch(
`https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/${userId}/reject`,
{
  method: "POST",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Content-Type": "application/json",
  },
  body: "{}",
}
);
```

**Go**

```go
req, _ := http.NewRequest("POST",
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/"+userID+"/reject",
  strings.NewReader("{}"))
req.Header.Set("Authorization", "Bearer "+token)
req.Header.Set("Content-Type", "application/json")

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

##### Response Example (200 OK)

```json
{ "userId": "abc123", "status": "pending" }
```

#### Error Responses

| Status | Description                                                                                                                                                                                                |
| ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | The user is neither "approved" nor a "suspended" user whose `emailVerified` is true (cannot revoke). A user whose approval was already revoked can be revoked again (a retry; no email is sent)            |
| `403`  | Missing users:manage scope                                                                                                                                                                                 |
| `404`  | User not found                                                                                                                                                                                             |
| `429`  | The limit on requests per source IP address (10 per minute) was exceeded (`code: "rate_limit_exceeded"`). Wait a moment and send it again                                                                  |
| `409`  | Another update of the same user is in progress (`code: "conflict"`)                                                                                                                                        |
| `500`  | The approval is revoked, but the stop of use could not be passed to the chat (`code: "user_suspension_incomplete"`). The user stays disabled and unapproved. Send the same request again to retry the stop |

### POST`/v1/admin/users/:userId/suspend`

Suspend a user. The approval status and data are kept, and the status in the list becomes "suspended". A suspended user cannot sign in. It also tries to end the user's signed-in sessions (if they cannot be ended, the suspension still succeeds, and sending the same request again tries again). Suspending also stops the user's running conversations and personal scheduled runs, deletes the user's own connections to external services (project connections are kept), and stops the sweeps and open workflow runs of the projects the user owns (the project definitions are kept). Resuming the user does not restore what was stopped. In a project owned by a suspended user, starting a workflow run and resuming a closed run are refused with `409 Conflict` (`principal_suspended`). Only approved users can be suspended. Sending the same operation again gives the same result. A token issued through the tenant cannot suspend the user of its own idp.sub (409).

#### Path Parameters

| パラメータ    | 型        | 必須 | 説明      |
| -------- | -------- | -- | ------- |
| `userId` | `string` | 必須 | User ID |

No body is needed (a body is not used even if sent).

#### Request Example

**Suspend user**

**curl**

```curl
curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/USER_ID/suspend \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.post(
  f"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/{user_id}/suspend",
  headers={"Authorization": f"Bearer {token}"},
)
```

**TypeScript**

```typescript
const response = await fetch(
`https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/${userId}/suspend`,
{
  method: "POST",
  headers: { "Authorization": "Bearer " + accessToken },
}
);
```

**Go**

```go
req, _ := http.NewRequest("POST",
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/"+userID+"/suspend",
  nil)
req.Header.Set("Authorization", "Bearer "+token)

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

##### Response Example (200 OK)

```json
{ "userId": "abc123", "suspended": true }
```

#### Error Responses

| Status | Description                                                                                                                                                                                                                                                            |
| ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | The body is malformed JSON (`code: "invalid_body"`)                                                                                                                                                                                                                    |
| `401`  | The token is invalid or missing (`code: "invalid_token"`)                                                                                                                                                                                                              |
| `403`  | Missing users:manage scope (`code: "insufficient_scope"`)                                                                                                                                                                                                              |
| `404`  | User not found (`code: "user_not_found"`)                                                                                                                                                                                                                              |
| `409`  | The user cannot be suspended (not approved, deleted, or permanently locked), the token tried to suspend the user of its own idp.sub, or another update of the same user is in progress (`code: "conflict"`). The error message and its guidance tell which one applies |
| `429`  | The limit on requests per source IP address (10 per minute) was exceeded (`code: "rate_limit_exceeded"`). Wait a moment and send it again                                                                                                                              |
| `500`  | The suspension was not fully applied (sign-in was stopped, but the change did not reach chat) (`code: "user_suspension_incomplete"`). Send the same request again                                                                                                      |
| `500`  | Another error (`code: "internal_error"`). Send the same request again                                                                                                                                                                                                  |

### POST`/v1/admin/users/:userId/resume`

Resume a suspended user. Sending the same operation again gives the same result.

#### Path Parameters

| パラメータ    | 型        | 必須 | 説明      |
| -------- | -------- | -- | ------- |
| `userId` | `string` | 必須 | User ID |

No body is needed (a body is not used even if sent).

#### Request Example

**Resume user**

**curl**

```curl
curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/USER_ID/resume \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.post(
  f"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/{user_id}/resume",
  headers={"Authorization": f"Bearer {token}"},
)
```

**TypeScript**

```typescript
const response = await fetch(
`https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/${userId}/resume`,
{
  method: "POST",
  headers: { "Authorization": "Bearer " + accessToken },
}
);
```

**Go**

```go
req, _ := http.NewRequest("POST",
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/"+userID+"/resume",
  nil)
req.Header.Set("Authorization", "Bearer "+token)

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

##### Response Example (200 OK)

```json
{ "userId": "abc123", "suspended": false }
```

#### Error Responses

| Status | Description                                                                                                                                                                                                  |
| ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `400`  | The body is malformed JSON (`code: "invalid_body"`)                                                                                                                                                          |
| `401`  | The token is invalid or missing (`code: "invalid_token"`)                                                                                                                                                    |
| `403`  | Missing users:manage scope (`code: "insufficient_scope"`)                                                                                                                                                    |
| `404`  | User not found (`code: "user_not_found"`)                                                                                                                                                                    |
| `409`  | The user cannot be resumed (not approved, deleted, or permanently locked), or another update of the same user is in progress (`code: "conflict"`). The error message and its guidance tell which one applies |
| `429`  | The limit on requests per source IP address (10 per minute) was exceeded (`code: "rate_limit_exceeded"`). Wait a moment and send it again                                                                    |
| `500`  | Resuming was not fully applied, and the user is still suspended (`code: "user_suspension_incomplete"`). Send the same request again                                                                          |
| `500`  | Another error. This is also returned when chat was resumed but sign-in could not be resumed (`code: "internal_error"`). Send the same request again                                                          |

### POST`/v1/admin/users/:userId/unlock`

Unlock a user who was locked out by failed sign-ins. If the user was not locked, nothing changes and wasLocked is false.

#### Path Parameters

| パラメータ    | 型        | 必須 | 説明      |
| -------- | -------- | -- | ------- |
| `userId` | `string` | 必須 | User ID |

No body is needed (a body is not used even if sent).

#### Request Example

**Unlock user**

**curl**

```curl
curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/USER_ID/unlock \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.post(
  f"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/{user_id}/unlock",
  headers={"Authorization": f"Bearer {token}"},
)
```

**TypeScript**

```typescript
const response = await fetch(
`https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/${userId}/unlock`,
{
  method: "POST",
  headers: { "Authorization": "Bearer " + accessToken },
}
);
```

**Go**

```go
req, _ := http.NewRequest("POST",
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/"+userID+"/unlock",
  nil)
req.Header.Set("Authorization", "Bearer "+token)

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

##### Response Example (200 OK)

```json
{ "userId": "abc123", "wasLocked": true }
```

#### Error Responses

| Status | Description                                                                                                                                |
| ------ | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `400`  | The body is malformed JSON (`code: "invalid_body"`)                                                                                        |
| `401`  | The token is invalid or missing (`code: "invalid_token"`)                                                                                  |
| `403`  | Missing users:manage scope (`code: "insufficient_scope"`)                                                                                  |
| `404`  | User not found (`code: "user_not_found"`)                                                                                                  |
| `409`  | Another update of the same user is in progress (`code: "conflict"`). Wait a moment and send it again                                       |
| `429`  | The limit on requests per source IP address (100 per minute) was exceeded (`code: "rate_limit_exceeded"`). Wait a moment and send it again |
| `500`  | The unlock could not be finished (`code: "internal_error"`). Send the same request again                                                   |

### PUT`/v1/admin/users/:userId/affiliation`

Change a user's affiliation (organization code) and job (job type code). Both are required. Look up the codes with GET /v1/organizations and GET /v1/job-types. The response has the values before and after the change (null for a previous value that was not set). Changing the affiliation removes the user's organization admin role and organization operations role in organizations other than the new one (the auditor role is kept). After a 500, the affiliation and job may already have changed. Sending the same request again redoes the cleanup of organization roles. For a user synced from the identity provider (IdP) (`users[].idpSynced` is `true` in GET /v1/admin/users), an organization or job type that is already set cannot be changed (409 `affiliation_managed_by_idp`). Change the organization and job type in the identity provider (IdP) that syncs this user. To fill in a value that is not set yet, send the current value for the one that is already set (`users[].organization.value` and `users[].jobType.value` in GET /v1/admin/users). An invalid code returns 400 before this check.

#### Path Parameters

| パラメータ    | 型        | 必須 | 説明      |
| -------- | -------- | -- | ------- |
| `userId` | `string` | 必須 | User ID |

#### Request Body

| パラメータ          | 型        | 必須 | 説明                                                     |
| -------------- | -------- | -- | ------------------------------------------------------ |
| `organization` | `string` | 必須 | Organization code (a value from GET /v1/organizations) |
| `job`          | `string` | 必須 | Job type code (a value from GET /v1/job-types)         |

#### Request Example

**Change user affiliation**

**curl**

```curl
curl -X PUT https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/USER_ID/affiliation \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{"organization": "ORG002", "job": "JOB01"}'
```

**Python**

```python
import requests

response = requests.put(
  f"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/{user_id}/affiliation",
  headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"},
  json={"organization": "ORG002", "job": "JOB01"},
)
```

**TypeScript**

```typescript
const response = await fetch(
`https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/${userId}/affiliation`,
{
  method: "PUT",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ organization: "ORG002", job: "JOB01" }),
}
);
```

**Go**

```go
body, _ := json.Marshal(map[string]string{"organization": "ORG002", "job": "JOB01"})
req, _ := http.NewRequest("PUT",
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/users/"+userID+"/affiliation",
  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()
```

##### Response Example (200 OK)

```json
{
  "userId": "abc123",
  "previous": { "organization": "ORG001", "job": null },
  "current": { "organization": "ORG002", "job": "JOB01" }
}
```

#### Error Responses

| Status | Description                                                                                                                                                                                                                                                                                                                                   |
| ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | organization or job is missing or not a string, or an organization or job type code is wrong (`code: "invalid_parameter"`)                                                                                                                                                                                                                    |
| `400`  | The body is malformed JSON or not a JSON object (`code: "invalid_body"`)                                                                                                                                                                                                                                                                      |
| `415`  | The body Content-Type is not application/json (`code: "unsupported_media_type"`)                                                                                                                                                                                                                                                              |
| `401`  | The token is invalid or missing (`code: "invalid_token"`)                                                                                                                                                                                                                                                                                     |
| `403`  | Missing users:manage scope (`code: "insufficient_scope"`)                                                                                                                                                                                                                                                                                     |
| `404`  | User not found (`code: "user_not_found"`)                                                                                                                                                                                                                                                                                                     |
| `409`  | Another update of the same user is in progress (`code: "conflict"`). Wait a moment and send it again                                                                                                                                                                                                                                          |
| `409`  | The organization and job type of this user are synced from the identity provider (IdP) and cannot be changed (`code: "affiliation_managed_by_idp"`). Change the organization and job type in the identity provider (IdP) that syncs this user. To fill in a value that is not set yet, send the current value for the one that is already set |
| `429`  | The limit on requests per source IP address (100 per minute) was exceeded (`code: "rate_limit_exceeded"`). Wait a moment and send it again                                                                                                                                                                                                    |
| `500`  | The change of affiliation and job could not be finished (`code: "internal_error"`). The affiliation and job may already have changed. Sending the same request again redoes the cleanup of organization roles                                                                                                                                 |

## Logs SaaS

View audit logs, operation audit logs, user action audit, LLM logs, LLM Gateway logs, LLM Gateway operation audit, access logs (records of outbound communication that was allowed or blocked), and guardrail alerts. The user action audit list uses cursor-based pagination and the other lists use page-based pagination. All lists support date range filters.

### Endpoint List

| メソッド | エンドポイント                             | 説明                               | スコープ        |
| ---- | ----------------------------------- | -------------------------------- | ----------- |
| GET  | `/v1/admin/audit-logs`              | List audit logs                  | `logs:read` |
| GET  | `/v1/admin/user-action-logs`        | List user action audit           | `logs:read` |
| GET  | `/v1/admin/action-audit-logs`       | List operation audit logs        | `logs:read` |
| GET  | `/v1/admin/llm-logs`                | List LLM logs                    | `logs:read` |
| GET  | `/v1/admin/llm-gateway-logs`        | List LLM Gateway logs            | `logs:read` |
| GET  | `/v1/admin/llm-gateway-action-logs` | List LLM Gateway operation audit | `logs:read` |
| GET  | `/v1/admin/access-logs`             | List access logs                 | `logs:read` |
| GET  | `/v1/admin/guardrail-alerts`        | List guardrail alerts            | `logs:read` |

### Common Query Parameters

| パラメータ   | 型         | 必須 | 説明                                                                                                                                                                                          |
| ------- | --------- | -- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `limit` | `integer` | —  | Number of items to fetch (1–100, default: 25. For the user action audit, default: 50)                                                                                                       |
| `page`  | `integer` | —  | Page number (1 or more, default: 1). Not used for the user action audit (use cursor)                                                                                                        |
| `from`  | `string`  | —  | Start date (an existing date in YYYY-MM-DD format, UTC). A value in another format, a date that does not exist, or a non-string value returns 400                                           |
| `to`    | `string`  | —  | End date (an existing date in YYYY-MM-DD format, UTC). Includes the end of the specified day. A value in another format, a date that does not exist, or a non-string value returns 400      |
| `order` | `string`  | —  | Sort order: "asc" or "desc" (default: "desc"), by the time column of each log. Other values return 400. Access logs and the user action audit are always newest first, and order is ignored |

### GET`/v1/admin/audit-logs`

List audit logs. By default, returned in descending order of creation date (use order for ascending).

#### Filter Query Parameters

| パラメータ      | 型        | 必須 | 説明                                                                     |
| ---------- | -------- | -- | ---------------------------------------------------------------------- |
| `resource` | `string` | —  | Exact match on the resource (resource)                                 |
| `action`   | `string` | —  | Exact match on the action (action)                                     |
| `user_id`  | `string` | —  | Exact match on the ID of the user who performed the operation (userId) |

#### Request Example

**List audit logs**

**curl**

```curl
curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/audit-logs?limit=10&from=2026-04-01&to=2026-04-15" \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/audit-logs",
  headers={"Authorization": f"Bearer {token}"},
  params={"limit": 10, "from": "2026-04-01", "to": "2026-04-15"},
)
```

**TypeScript**

```typescript
const params = new URLSearchParams({ limit: "10", from: "2026-04-01", to: "2026-04-15" });
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/audit-logs?" + params,
{
  headers: { "Authorization": "Bearer " + accessToken },
}
);
```

**Go**

```go
req, _ := http.NewRequest("GET",
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/audit-logs?limit=10&from=2026-04-01&to=2026-04-15",
  nil)
req.Header.Set("Authorization", "Bearer "+token)

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

#### Response Fields (200 OK)

| Field                    | Type             | Description                                                                                                                                                                                     |
| ------------------------ | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `auditLogs`              | `array`          | Array of audit log objects                                                                                                                                                                      |
| `auditLogs[].auditLogId` | `string`         | Audit log ID                                                                                                                                                                                    |
| `auditLogs[].resource`   | `string`         | Resource operated on (e.g. users/show, config/organizations/create, config/job-types/edit)                                                                                                      |
| `auditLogs[].action`     | `string`         | Operation action (approve / reject / promote / demote / create / update / delete / reset-password, etc.). For records whose meta has an action, that value (same as shown in the admin console) |
| `auditLogs[].meta`       | `object \| null` | Additional metadata                                                                                                                                                                             |
| `auditLogs[].userId`     | `string`         | User ID who performed the operation. For operations with a system integration token (Client Credentials flow), client:\<client ID>                                                              |
| `auditLogs[].userEmail`  | `string \| null` | Email address of the user                                                                                                                                                                       |
| `auditLogs[].userName`   | `string \| null` | Display name of the user. For operations with a system integration token (Client Credentials flow), the client name                                                                             |
| `auditLogs[].ipAddress`  | `string \| null` | IP address                                                                                                                                                                                      |
| `auditLogs[].userAgent`  | `string \| null` | User-Agent                                                                                                                                                                                      |
| `auditLogs[].createdAt`  | `string`         | Creation date and time (ISO 8601)                                                                                                                                                               |
| `total`                  | `integer`        | Total count                                                                                                                                                                                     |
| `limit`                  | `integer`        | Number of items fetched                                                                                                                                                                         |
| `page`                   | `integer`        | Page number                                                                                                                                                                                     |
| `hasMore`                | `boolean`        | Whether the next page exists                                                                                                                                                                    |

##### Example Response (200 OK)

```json
{
  "auditLogs": [
    {
      "auditLogId": "6b4366a3-791d-4f60-a9ef-24bdb3303e36",
      "resource": "users/list",
      "action": "approve",
      "meta": {
        "userName": "user2@example.com",
        "timestamp": "2026-04-19T13:03:27.238Z",
        "isApproved": true
      },
      "userId": "41b9fcf1-958d-4a86-a863-804b69224a1d",
      "userEmail": "admin@example.com",
      "userName": "admin@example.com",
      "ipAddress": "203.0.113.140",
      "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/146.0.0.0 Safari/537.36",
      "createdAt": "2026-04-19T13:03:27.479Z"
    },
    {
      "auditLogId": "c14d6065-7c35-44f6-8eea-033ede09bf3a",
      "resource": "users/show",
      "action": "delete",
      "meta": {
        "userName": "user1@example.com",
        "timestamp": "2026-04-19T05:04:19.745Z",
        "userEmail": "user1@example.com"
      },
      "userId": "client:billing-integration",
      "userEmail": "service-account-client@federation.invalid",
      "userName": "Billing integration",
      "ipAddress": "198.51.100.23",
      "userAgent": "Mozilla/5.0 (...)",
      "createdAt": "2026-04-19T05:04:19.876Z"
    },
    {
      "auditLogId": "f84ef377-9d75-4875-9958-b084c91a3c9b",
      "resource": "organizations",
      "action": "delete",
      "meta": {},
      "userId": "client:billing-integration",
      "userEmail": "service-account-client@federation.invalid",
      "userName": "Billing integration",
      "ipAddress": "198.51.100.23",
      "userAgent": "Mozilla/5.0 (...)",
      "createdAt": "2026-04-19T05:02:01.736Z"
    }
  ],
  "total": 1537,
  "limit": 3,
  "page": 1,
  "hasMore": true
}
```

### GET`/v1/admin/user-action-logs`

List the user action audit: records of actions users performed in the chat (opening, creating or deleting conversations, files, shares and so on). Always newest first, with [cursor-based](#cursor-based) pagination (`limit` is 1–100, default 50). Message content is not recorded. The “Metadata” shown on the screen (fingerprinted IP addresses and user agents, and so on) is not returned.

- Without a period (`from` and `to`), the last 30 days are returned. Without `from` only, the 30 days up to the `to` date; without `to` only, up to now. A `from` later than `to` returns 400.
- From the second page on, send the same `user_id` and `action` as the first page together with `cursor`. Changing the conditions changes the range and can cause duplicate or missing items. The period of the first page is kept in `cursor`, so `from` and `to` sent with later pages do not change it.
- Even when fewer items than `limit` are returned, there are more while `hasMore` is `true`.

#### Filter Query Parameters

| パラメータ     | 型        | 必須 | 説明                                                                         |
| --------- | -------- | -- | -------------------------------------------------------------------------- |
| `user_id` | `string` | —  | Exact match on the ID of the user who acted (userId), up to 128 characters |
| `action`  | `string` | —  | Exact match on the action (action), up to 64 characters                    |

An empty value does not filter. A value of only whitespace, a value with leading or trailing whitespace, a value that is too long, or a parameter given twice or more returns 400.

#### Request Example

**List user action logs**

**curl**

```curl
curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/user-action-logs?limit=50&from=2026-11-01&to=2026-11-10&action=export" \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/user-action-logs",
  headers={"Authorization": f"Bearer {token}"},
  params={"limit": 50, "from": "2026-11-01", "to": "2026-11-10", "action": "export"},
)
```

**TypeScript**

```typescript
const params = new URLSearchParams({ limit: "50", from: "2026-11-01", to: "2026-11-10", action: "export" });
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/user-action-logs?" + params,
{
  headers: { "Authorization": "Bearer " + accessToken },
}
);
```

**Go**

```go
req, _ := http.NewRequest("GET",
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/user-action-logs?limit=50&from=2026-11-01&to=2026-11-10&action=export",
  nil)
req.Header.Set("Authorization", "Bearer "+token)

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

For the second page, send the `cursor` from the first response with the same filters (`action` in this example).

```bash
curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/user-action-logs?limit=50&action=export&cursor=<cursor from the previous response>" \
  -H "Authorization: Bearer <access_token>"
```

#### Response Fields (200 OK)

| Field                              | Type             | Description                                                                                  |
| ---------------------------------- | ---------------- | -------------------------------------------------------------------------------------------- |
| `userActionLogs`                   | `array`          | Array of user action audit records                                                           |
| `userActionLogs[].userActionLogId` | `string`         | User action audit ID                                                                         |
| `userActionLogs[].occurredAt`      | `string`         | When the action took place (ISO 8601)                                                        |
| `userActionLogs[].eventType`       | `string`         | Type, in the form user\_action.\<resource>.\<action> (e.g. user\_action.conversation.export) |
| `userActionLogs[].userId`          | `string \| null` | ID of the user who acted. null when unknown                                                  |
| `userActionLogs[].actorKind`       | `string`         | Actor (human: a user / unknown: the user is not known)                                       |
| `userActionLogs[].resource`        | `string \| null` | Resource (e.g. conversation, share, session)                                                 |
| `userActionLogs[].action`          | `string \| null` | Action (e.g. export, delete)                                                                 |
| `userActionLogs[].decision`        | `string`         | Result (e.g. allow, deny, rejected, not\_found, error, aborted)                              |
| `userActionLogs[].requestId`       | `string \| null` | Request ID                                                                                   |
| `userActionLogs[].conversationId`  | `string \| null` | Conversation ID                                                                              |
| `userActionLogs[].systemVersion`   | `string \| null` | System version when recorded                                                                 |
| `hasMore`                          | `boolean`        | Whether a next page exists                                                                   |
| `cursor`                           | `string?`        | Only when hasMore is true. Cursor value for the next page                                    |

##### Response Example (200 OK)

```json
{
  "userActionLogs": [
    {
      "userActionLogId": "48213",
      "occurredAt": "2026-11-10T02:15:30.123Z",
      "eventType": "user_action.conversation.export",
      "userId": "41b9fcf1-958d-4a86-a863-804b69224a1d",
      "actorKind": "human",
      "resource": "conversation",
      "action": "export",
      "decision": "allow",
      "requestId": "7f3c2a1e-9b8d-4c6f-a5e4-3d2c1b0a9f8e",
      "conversationId": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
      "systemVersion": "3.4.0"
    }
  ],
  "hasMore": true,
  "cursor": "eyJjIjoiTWpBeU5pMHhNUzB4TUZRd01qb3hOVG96TUM0eE1qTmFmRFE0TWpFeiIsImYiOiIyMDI2LTExLTAxVDAwOjAwOjAwLjAwMFoiLCJ0IjoiMjAyNi0xMS0xMVQwMDowMDowMC4wMDBaIiwiZSI6dHJ1ZX0"
}
```

#### Error Responses

| Status | Description                                                                                                                                                                                                                                                                                                      |
| ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | limit is not 1–100; from or to is not an existing date in YYYY-MM-DD format; from is later than to; user\_id or action is only whitespace, has leading or trailing whitespace, is too long, or is given twice or more; or cursor is invalid (not a value from a previous response) (`code: "invalid_parameter"`) |
| `400`  | The service did not accept the period (e.g. to is omitted and from is a date after today) (`code: "bad_request"`)                                                                                                                                                                                                |
| `403`  | Missing logs:read scope (`code: "insufficient_scope"`)                                                                                                                                                                                                                                                           |

### GET`/v1/admin/action-audit-logs`

List operation audit logs: what users, agents and the system carried out, such as agents' tool calls, allows and denies by execution rules, and approvals. By default, returned in descending order of occurrence time (use order for ascending). The text itself is not recorded. The “Integrity Hash of Record Content”, “Row Hash” and “Metadata” shown on the screen are not returned.

#### Filter Query Parameters

| パラメータ               | 型        | 必須 | 説明                                                                                                                                  |
| ------------------- | -------- | -- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `event_type`        | `string` | —  | Exact match on the event type (eventType), e.g. "tool.invoked", "approval.resolved", "gate.resolved", "run.started", "agent.copied" |
| `decision`          | `string` | —  | Exact match on the decision (decision), e.g. "allow", "deny", "completed", "failed", "copied"                                       |
| `source`            | `string` | —  | Exact match on the source (source), e.g. "worker", "cli-api", "front", "admin", "login", "agent\_executor"                          |
| `actor_type`        | `string` | —  | Exact match on the actor type (actorType), e.g. "human", "agent", "system"                                                          |
| `actor_kind`        | `string` | —  | Exact match on the actor kind (actorKind), e.g. "human", "human\_external", "system", "agent", "unknown"                            |
| `actor_ref`         | `string` | —  | Exact match on the actor (actorRef)                                                                                                 |
| `conversation_id`   | `string` | —  | Exact match on the conversation ID (conversationId)                                                                                 |
| `execution_id`      | `string` | —  | Exact match on the execution ID (executionId)                                                                                       |
| `root_execution_id` | `string` | —  | Exact match on the execution series ID (rootExecutionId)                                                                            |
| `project_id`        | `string` | —  | Exact match on the project ID (projectId). A value that is not a UUID returns 400                                                   |
| `request_id`        | `string` | —  | Exact match on the request ID (requestId)                                                                                           |

Values are not restricted, and an unknown value matches nothing. An empty value does not filter. A value of only whitespace, a value with leading or trailing whitespace, or a parameter given twice or more returns 400.

#### Request Example

**List action audit logs**

**curl**

```curl
curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/action-audit-logs?limit=10&from=2026-11-01&to=2026-11-10&source=front" \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/action-audit-logs",
  headers={"Authorization": f"Bearer {token}"},
  params={"limit": 10, "from": "2026-11-01", "to": "2026-11-10", "source": "front"},
)
```

**TypeScript**

```typescript
const params = new URLSearchParams({ limit: "10", from: "2026-11-01", to: "2026-11-10", source: "front" });
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/action-audit-logs?" + params,
{
  headers: { "Authorization": "Bearer " + accessToken },
}
);
```

**Go**

```go
req, _ := http.NewRequest("GET",
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/action-audit-logs?limit=10&from=2026-11-01&to=2026-11-10&source=front",
  nil)
req.Header.Set("Authorization", "Bearer "+token)

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

#### Response Fields (200 OK)

| Field                                | Type             | Description                                                                              |
| ------------------------------------ | ---------------- | ---------------------------------------------------------------------------------------- |
| `actionAuditLogs`                    | `array`          | Array of operation audit log objects                                                     |
| `actionAuditLogs[].actionAuditLogId` | `string`         | Operation audit log ID                                                                   |
| `actionAuditLogs[].occurredAt`       | `string \| null` | Occurred at (ISO 8601)                                                                   |
| `actionAuditLogs[].source`           | `string \| null` | Source (e.g. worker, cli-api, front, admin, login, agent\_executor)                      |
| `actionAuditLogs[].eventType`        | `string \| null` | Event type                                                                               |
| `actionAuditLogs[].actorType`        | `string \| null` | Actor type (e.g. human, agent, system)                                                   |
| `actionAuditLogs[].actorKind`        | `string \| null` | Actor kind (e.g. human, human\_external, system, agent, unknown). null for older records |
| `actionAuditLogs[].actorRef`         | `string \| null` | Actor                                                                                    |
| `actionAuditLogs[].onBehalfOfRef`    | `string \| null` | On behalf of (whom the action was carried out for)                                       |
| `actionAuditLogs[].resource`         | `string \| null` | Resource                                                                                 |
| `actionAuditLogs[].action`           | `string \| null` | Action                                                                                   |
| `actionAuditLogs[].decision`         | `string \| null` | Decision                                                                                 |
| `actionAuditLogs[].reason`           | `string \| null` | Reason code                                                                              |
| `actionAuditLogs[].policyId`         | `string \| null` | Execution rules ID                                                                       |
| `actionAuditLogs[].policyVersion`    | `string \| null` | Execution rules version                                                                  |
| `actionAuditLogs[].executionId`      | `string \| null` | Execution ID                                                                             |
| `actionAuditLogs[].rootExecutionId`  | `string \| null` | Execution series ID. null for older records                                              |
| `actionAuditLogs[].conversationId`   | `string \| null` | Conversation ID                                                                          |
| `actionAuditLogs[].projectId`        | `string \| null` | Project ID. null for older records                                                       |
| `actionAuditLogs[].messageId`        | `string \| null` | Message ID                                                                               |
| `actionAuditLogs[].requestId`        | `string \| null` | Request ID                                                                               |
| `actionAuditLogs[].systemVersion`    | `string \| null` | System version                                                                           |
| `total`                              | `integer`        | Total count                                                                              |
| `limit`                              | `integer`        | Number of items fetched                                                                  |
| `page`                               | `integer`        | Page number                                                                              |
| `hasMore`                            | `boolean`        | Whether a next page exists                                                               |

##### Response Example (200 OK)

```json
{
  "actionAuditLogs": [
    {
      "actionAuditLogId": "1203344",
      "occurredAt": "2026-11-10T03:00:12.456Z",
      "source": "front",
      "eventType": "agent.copied",
      "actorType": "human",
      "actorKind": "human",
      "actorRef": "41b9fcf1-958d-4a86-a863-804b69224a1d",
      "onBehalfOfRef": null,
      "resource": "agent:9c8b7a6f-5e4d-4c3b-8a2f-1e0d9c8b7a6f",
      "action": null,
      "decision": "copied",
      "reason": null,
      "policyId": null,
      "policyVersion": null,
      "executionId": null,
      "rootExecutionId": null,
      "conversationId": null,
      "projectId": null,
      "messageId": null,
      "requestId": null,
      "systemVersion": "3.4.0"
    }
  ],
  "total": 128,
  "limit": 1,
  "page": 1,
  "hasMore": true
}
```

#### Error Responses

| Status | Description                                                                                                                                                                                              |
| ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | limit, page, from, to, or order is invalid; a filter value is only whitespace, has leading or trailing whitespace, or is given twice or more; or project\_id is not a UUID (`code: "invalid_parameter"`) |
| `403`  | Missing logs:read scope (`code: "insufficient_scope"`)                                                                                                                                                   |

### GET`/v1/admin/llm-logs`

List LLM logs. By default, returned in descending order of timestamp (use order for ascending).

#### Filter Query Parameters

| パラメータ             | 型        | 必須 | 説明                                                              |
| ----------------- | -------- | -- | --------------------------------------------------------------- |
| `conversation_id` | `string` | —  | Exact match on the conversation ID (conversationId)             |
| `service`         | `string` | —  | Exact match on the service (service)                            |
| `operation`       | `string` | —  | Exact match on the operation (operation)                        |
| `success`         | `string` | —  | "true" (succeeded) or "false" (failed). Other values return 400 |

#### Request Example

**List LLM logs**

**curl**

```curl
curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/llm-logs?limit=10" \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/llm-logs",
  headers={"Authorization": f"Bearer {token}"},
  params={"limit": 10},
)
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/llm-logs?limit=10",
{
  headers: { "Authorization": "Bearer " + accessToken },
}
);
```

**Go**

```go
req, _ := http.NewRequest("GET",
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/llm-logs?limit=10",
  nil)
req.Header.Set("Authorization", "Bearer "+token)

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

#### Response Fields (200 OK)

| Field                         | Type              | Description                                                                                                                                                                                                                                                     |
| ----------------------------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `llmLogs`                     | `array`           | Array of LLM log objects                                                                                                                                                                                                                                        |
| `llmLogs[].llmLogId`          | `string`          | LLM log ID                                                                                                                                                                                                                                                      |
| `llmLogs[].timestamp`         | `string \| null`  | Timestamp                                                                                                                                                                                                                                                       |
| `llmLogs[].service`           | `string \| null`  | Service name                                                                                                                                                                                                                                                    |
| `llmLogs[].operation`         | `string \| null`  | Operation name                                                                                                                                                                                                                                                  |
| `llmLogs[].durationMs`        | `number \| null`  | Processing time (milliseconds)                                                                                                                                                                                                                                  |
| `llmLogs[].conversationId`    | `string \| null`  | Conversation ID                                                                                                                                                                                                                                                 |
| `llmLogs[].intentType`        | `string \| null`  | Intent type                                                                                                                                                                                                                                                     |
| `llmLogs[].confidenceScore`   | `number \| null`  | Confidence score                                                                                                                                                                                                                                                |
| `llmLogs[].toolsUsed`         | `number \| null`  | Number of tool calls — not a list of tool names, and not a count of distinct tools (calling the same tool 5 times gives 5). `null` means not measured; `0` means the run was measured and made no tool call. The two are distinct — do not treat `0` as `null`. |
| `llmLogs[].success`           | `boolean \| null` | Success/failure                                                                                                                                                                                                                                                 |
| `llmLogs[].agentType`         | `string \| null`  | Agent type                                                                                                                                                                                                                                                      |
| `llmLogs[].agentLevel`        | `string \| null`  | Agent level                                                                                                                                                                                                                                                     |
| `llmLogs[].taskComplexity`    | `string \| null`  | Task complexity                                                                                                                                                                                                                                                 |
| `llmLogs[].currentMessage`    | `string \| null`  | Current message                                                                                                                                                                                                                                                 |
| `llmLogs[].contextSummary`    | `string \| null`  | Context summary                                                                                                                                                                                                                                                 |
| `llmLogs[].suggestedApproach` | `string \| null`  | Suggested approach                                                                                                                                                                                                                                              |
| `llmLogs[].conversationGoal`  | `string \| null`  | Conversation goal                                                                                                                                                                                                                                               |
| `llmLogs[].finalContent`      | `string \| null`  | Final output content                                                                                                                                                                                                                                            |
| `llmLogs[].metadata`          | `object \| null`  | Supplementary metadata that varies by operation (keys vary)                                                                                                                                                                                                     |
| `llmLogs[].createdAt`         | `string \| null`  | Creation date and time                                                                                                                                                                                                                                          |
| `total`                       | `integer`         | Total count                                                                                                                                                                                                                                                     |
| `limit`                       | `integer`         | Number of items fetched                                                                                                                                                                                                                                         |
| `page`                        | `integer`         | Page number                                                                                                                                                                                                                                                     |
| `hasMore`                     | `boolean`         | Whether the next page exists                                                                                                                                                                                                                                    |

##### Example Response (200 OK)

```json
{
  "llmLogs": [
    {
      "llmLogId": "33098",
      "timestamp": "2026-04-19T04:12:51.102Z",
      "service": "agent-executor",
      "operation": "agent.intent.completed",
      "durationMs": 5574.6,
      "conversationId": "3b72544d-d6b5-4577-b5f3-c39293124a57",
      "intentType": "complex_task",
      "confidenceScore": 0.95,
      "toolsUsed": null,
      "success": null,
      "agentType": "intent",
      "agentLevel": "default",
      "taskComplexity": null,
      "currentMessage": "Tell me about this URL https://example.com/path",
      "contextSummary": "User is asking about a URL.",
      "suggestedApproach": "execute_single_tool",
      "conversationGoal": "Information about the contents or purpose of the specified URL",
      "finalContent": null,
      "metadata": {
        "message.id": "02038f42-154b-4363-9beb-d31512934ec5",
        "task.complexity": "moderate",
        "detected_language": "en",
        "requires_planning": true
      },
      "createdAt": "2026-04-18T19:16:16.964Z"
    },
    {
      "llmLogId": "33097",
      "timestamp": "2026-04-19T04:12:48.730Z",
      "service": "agent-executor",
      "operation": "agent.guardrail.completed",
      "durationMs": 3170.34,
      "conversationId": "3b72544d-d6b5-4577-b5f3-c39293124a57",
      "intentType": null,
      "confidenceScore": null,
      "toolsUsed": null,
      "success": null,
      "agentType": "intent.guardrails",
      "agentLevel": null,
      "taskComplexity": null,
      "currentMessage": null,
      "contextSummary": null,
      "suggestedApproach": null,
      "conversationGoal": null,
      "finalContent": null,
      "metadata": { "guardrail_detected": false },
      "createdAt": "2026-04-18T19:16:14.619Z"
    },
    {
      "llmLogId": "33096",
      "timestamp": "2026-04-19T04:12:33.662Z",
      "service": "agent-executor",
      "operation": "agent.intent.completed",
      "durationMs": 4213.47,
      "conversationId": "4d7c798d-2e3e-4d40-86ab-cbb6c685a3fb",
      "intentType": "conversation",
      "confidenceScore": 1,
      "toolsUsed": null,
      "success": null,
      "agentType": "intent",
      "agentLevel": "default",
      "taskComplexity": null,
      "currentMessage": "Hello",
      "contextSummary": "New conversation. User is greeting.",
      "suggestedApproach": "conversational_response",
      "conversationGoal": "Greeting exchange with the AI assistant",
      "finalContent": null,
      "metadata": {
        "message.id": "cea9dbcc-4723-452a-bdcd-aa5f3a0e9ca6",
        "task.complexity": "simple",
        "detected_language": "en",
        "requires_planning": false
      },
      "createdAt": "2026-04-18T19:15:59.681Z"
    }
  ],
  "total": 33098,
  "limit": 3,
  "page": 1,
  "hasMore": true
}
```

### GET`/v1/admin/llm-gateway-logs`

List LLM Gateway logs. By default, returned in descending order of creation time (use order for ascending). One request = one row, recording usage such as model, provider, tokens, cost, and latency.

#### Filter Query Parameters

| パラメータ        | 型        | 必須 | 説明                                                                                   |
| ------------ | -------- | -- | ------------------------------------------------------------------------------------ |
| `provider`   | `string` | —  | Exact match on the provider (provider)                                               |
| `model_name` | `string` | —  | Exact match on the model name (rows without modelName are compared by resolvedModel) |
| `success`    | `string` | —  | "true" (succeeded) or "false" (failed). Other values return 400                      |

#### Request Example

**List LLM gateway logs**

**curl**

```curl
curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/llm-gateway-logs?limit=10" \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/llm-gateway-logs",
  headers={"Authorization": f"Bearer {token}"},
  params={"limit": 10},
)
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/llm-gateway-logs?limit=10",
{
  headers: { "Authorization": "Bearer " + accessToken },
}
);
```

**Go**

```go
req, _ := http.NewRequest("GET",
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/llm-gateway-logs?limit=10",
  nil)
req.Header.Set("Authorization", "Bearer "+token)

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

#### Response Fields (200 OK)

| Field                                      | Type                     | Description                        |
| ------------------------------------------ | ------------------------ | ---------------------------------- |
| llmGatewayLogs                             | array                    | Array of LLM Gateway log objects   |
| llmGatewayLogs\[].llmGatewayLogId          | string                   | LLM Gateway log ID                 |
| llmGatewayLogs\[].createdAt                | string \| null           | Creation date and time             |
| llmGatewayLogs\[].virtualKeyId             | string \| null           | Virtual key ID (calling client)    |
| llmGatewayLogs\[].clientSessionId          | string \| null           | Client session ID                  |
| llmGatewayLogs\[].clientAgentId            | string \| null           | Client agent ID                    |
| llmGatewayLogs\[].apiFlavor                | string \| null           | API flavor                         |
| llmGatewayLogs\[].modelName                | string \| null           | Model name (as requested)          |
| llmGatewayLogs\[].resolvedModel            | string \| null           | Resolved model name                |
| llmGatewayLogs\[].provider                 | string \| null           | Provider                           |
| llmGatewayLogs\[].deployment               | string \| null           | Deployment                         |
| llmGatewayLogs\[].tier                     | string \| null           | Tier                               |
| llmGatewayLogs\[].stream                   | boolean \| null          | Whether streaming was used         |
| llmGatewayLogs\[].success                  | boolean \| null          | Success/failure                    |
| llmGatewayLogs\[].httpStatus               | number \| null           | HTTP status                        |
| llmGatewayLogs\[].errorType                | string \| null           | Error type                         |
| llmGatewayLogs\[].errorCode                | string \| null           | Error code                         |
| llmGatewayLogs\[].usageStatus              | string \| null           | Usage status                       |
| llmGatewayLogs\[].latencyMs                | number \| null           | Latency (milliseconds)             |
| llmGatewayLogs\[].inputTokens              | number \| null           | Input token count                  |
| llmGatewayLogs\[].outputTokens             | number \| null           | Output token count                 |
| llmGatewayLogs\[].totalTokens              | number \| null           | Total token count                  |
| llmGatewayLogs\[].cachedTokens             | number \| null           | Cached token count                 |
| llmGatewayLogs\[].cacheCreationInputTokens | number \| null           | Cache creation input token count   |
| llmGatewayLogs\[].reasoningTokens          | number \| null           | Reasoning token count              |
| llmGatewayLogs\[].costUsd                  | number \| string \| null | Cost (USD)                         |
| llmGatewayLogs\[].currency                 | string \| null           | Currency                           |
| llmGatewayLogs\[].metadata                 | object \| null           | Supplementary metadata (keys vary) |
| total                                      | integer                  | Total count                        |
| limit                                      | integer                  | Number of items fetched            |
| page                                       | integer                  | Page number                        |
| hasMore                                    | boolean                  | Whether the next page exists       |

### GET`/v1/admin/llm-gateway-action-logs`

List the LLM Gateway operation audit: a record of operations performed through the LLM Gateway. There are no records if you do not use the LLM Gateway. By default, returned in descending order of occurrence time (use order for ascending). The “Request ID”, “Detail Digest”, “Row Hash” and “Metadata” shown on the screen are not returned.

#### Filter Query Parameters

| パラメータ            | 型        | 必須 | 説明                                                                                                                                                                                 |
| ---------------- | -------- | -- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `event_type`     | `string` | —  | Exact match on the event type (eventType), e.g. "auth.denied", "guardrail.blocked", "policy.pii\_blocked", "policy.mcp\_stripped", "limit.rpm\_exceeded", "limit.budget\_exceeded" |
| `decision`       | `string` | —  | Exact match on the decision (decision), e.g. "allowed", "denied", "blocked", "degraded", "stripped", "throttled"                                                                   |
| `api_flavor`     | `string` | —  | Exact match on the API flavor (apiFlavor), e.g. "chat", "responses", "messages", "embeddings"                                                                                      |
| `virtual_key_id` | `string` | —  | Exact match on the virtual key ID (virtualKeyId)                                                                                                                                   |

Values are not restricted, and an unknown value matches nothing. An empty value does not filter. A value of only whitespace, a value with leading or trailing whitespace, or a parameter given twice or more returns 400.

#### Request Example

**List LLM gateway action logs**

**curl**

```curl
curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/llm-gateway-action-logs?limit=10&event_type=guardrail.blocked" \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/llm-gateway-action-logs",
  headers={"Authorization": f"Bearer {token}"},
  params={"limit": 10, "event_type": "guardrail.blocked"},
)
```

**TypeScript**

```typescript
const params = new URLSearchParams({ limit: "10", event_type: "guardrail.blocked" });
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/llm-gateway-action-logs?" + params,
{
  headers: { "Authorization": "Bearer " + accessToken },
}
);
```

**Go**

```go
req, _ := http.NewRequest("GET",
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/llm-gateway-action-logs?limit=10&event_type=guardrail.blocked",
  nil)
req.Header.Set("Authorization", "Bearer "+token)

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

#### Response Fields (200 OK)

| Field                                          | Type             | Description                                  |
| ---------------------------------------------- | ---------------- | -------------------------------------------- |
| `llmGatewayActionLogs`                         | `array`          | Array of LLM Gateway operation audit objects |
| `llmGatewayActionLogs[].llmGatewayActionLogId` | `string`         | LLM Gateway operation audit ID               |
| `llmGatewayActionLogs[].occurredAt`            | `string \| null` | Occurred at (ISO 8601)                       |
| `llmGatewayActionLogs[].virtualKeyId`          | `string \| null` | Virtual key ID (calling client)              |
| `llmGatewayActionLogs[].externalRequestId`     | `string \| null` | External request ID                          |
| `llmGatewayActionLogs[].apiFlavor`             | `string \| null` | API flavor                                   |
| `llmGatewayActionLogs[].eventType`             | `string \| null` | Event type                                   |
| `llmGatewayActionLogs[].decision`              | `string \| null` | Decision                                     |
| `llmGatewayActionLogs[].reason`                | `string \| null` | Reason code                                  |
| `llmGatewayActionLogs[].modelName`             | `string \| null` | Model name (as requested)                    |
| `llmGatewayActionLogs[].resolvedModel`         | `string \| null` | Resolved model name                          |
| `llmGatewayActionLogs[].systemVersion`         | `string \| null` | System version                               |
| `total`                                        | `integer`        | Total count                                  |
| `limit`                                        | `integer`        | Number of items fetched                      |
| `page`                                         | `integer`        | Page number                                  |
| `hasMore`                                      | `boolean`        | Whether a next page exists                   |

##### Response Example (200 OK)

```json
{
  "llmGatewayActionLogs": [
    {
      "llmGatewayActionLogId": "88412",
      "occurredAt": "2026-11-10T04:21:07.318Z",
      "virtualKeyId": "3f2e1d0c-9b8a-4765-8432-10fedcba9876",
      "externalRequestId": null,
      "apiFlavor": "chat",
      "eventType": "guardrail.blocked",
      "decision": "blocked",
      "reason": null,
      "modelName": "<model ID>",
      "resolvedModel": "<model ID>",
      "systemVersion": "3.4.0"
    }
  ],
  "total": 3,
  "limit": 10,
  "page": 1,
  "hasMore": false
}
```

#### Error Responses

| Status | Description                                                                                                                                                                   |
| ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | limit, page, from, to, or order is invalid; or a filter value is only whitespace, has leading or trailing whitespace, or is given twice or more (`code: "invalid_parameter"`) |
| `403`  | Missing logs:read scope (`code: "insufficient_scope"`)                                                                                                                        |

### GET`/v1/admin/access-logs`

List access logs. Access logs are records of outbound communication that was allowed or blocked. Returned in descending order of timestamp (order cannot be specified).

#### Filter Query Parameters

| パラメータ          | 型        | 必須 | 説明                                             |
| -------------- | -------- | -- | ---------------------------------------------- |
| `authz_result` | `string` | —  | "allowed" or "denied". Other values return 400 |

#### Request Example

**List access logs**

**curl**

```curl
curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/access-logs?limit=10" \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/access-logs",
  headers={"Authorization": f"Bearer {token}"},
  params={"limit": 10},
)
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/access-logs?limit=10",
{
  headers: { "Authorization": "Bearer " + accessToken },
}
);
```

**Go**

```go
req, _ := http.NewRequest("GET",
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/access-logs?limit=10",
  nil)
req.Header.Set("Authorization", "Bearer "+token)

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

#### Response Fields (200 OK)

| Field                          | Type             | Description                                                                                            |
| ------------------------------ | ---------------- | ------------------------------------------------------------------------------------------------------ |
| `accessLogs`                   | `array`          | Array of access log objects                                                                            |
| `accessLogs[].timestamp`       | `string`         | Timestamp                                                                                              |
| `accessLogs[].sourceNamespace` | `string \| null` | Source namespace                                                                                       |
| `accessLogs[].sourceIp`        | `string \| null` | Source IP address                                                                                      |
| `accessLogs[].method`          | `string \| null` | HTTP method                                                                                            |
| `accessLogs[].host`            | `string \| null` | Host name                                                                                              |
| `accessLogs[].path`            | `string \| null` | Request path                                                                                           |
| `accessLogs[].userAgent`       | `string \| null` | User-Agent                                                                                             |
| `accessLogs[].statusCode`      | `number \| null` | HTTP status code                                                                                       |
| `accessLogs[].durationMs`      | `number \| null` | Processing time (milliseconds)                                                                         |
| `accessLogs[].authzResult`     | `string \| null` | Authorization result                                                                                   |
| `accessLogs[].authzReason`     | `string \| null` | Authorization reason                                                                                   |
| `total`                        | `integer`        | Total count                                                                                            |
| `limit`                        | `integer`        | Number of items fetched                                                                                |
| `page`                         | `integer`        | Page number                                                                                            |
| `hasMore`                      | `boolean`        | Whether the next page exists                                                                           |
| `skippedCount`                 | `integer`        | Number of log rows on this page that could not be read (not included in accessLogs; total counts them) |

##### Example Response (200 OK)

```json
{
  "accessLogs": [
    {
      "timestamp": "2026-04-19T05:17:36.735896",
      "sourceNamespace": "autonomous-agent",
      "sourceIp": "127.0.0.1",
      "method": "CONNECT",
      "host": "optimizationguide-pa.googleapis.com:443",
      "path": "",
      "userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/147.0.0.0 Safari/537.36",
      "statusCode": 200,
      "durationMs": 1,
      "authzResult": "allowed",
      "authzReason": "allowed:  All allow"
    },
    {
      "timestamp": "2026-04-19T03:50:36.766451",
      "sourceNamespace": "autonomous-agent",
      "sourceIp": "127.0.0.1",
      "method": "CONNECT",
      "host": "update.googleapis.com:443",
      "path": "",
      "userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/147.0.0.0 Safari/537.36",
      "statusCode": 200,
      "durationMs": 6,
      "authzResult": "allowed",
      "authzReason": "allowed:  All allow"
    },
    {
      "timestamp": "2026-04-19T03:45:48.481023",
      "sourceNamespace": "autonomous-agent",
      "sourceIp": "127.0.0.1",
      "method": "CONNECT",
      "host": "optimizationguide-pa.googleapis.com:443",
      "path": "",
      "userAgent": "Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/147.0.0.0 Safari/537.36",
      "statusCode": 200,
      "durationMs": 0,
      "authzResult": "allowed",
      "authzReason": "allowed:  All allow"
    }
  ],
  "total": 57806,
  "limit": 3,
  "page": 1,
  "hasMore": true,
  "skippedCount": 0
}
```

### GET`/v1/admin/guardrail-alerts`

Lists guardrail alerts. By default, results are returned in descending order of detection time (use order for ascending).

#### Filter Query Parameters

| パラメータ                 | 型        | 必須 | 説明                                                                                                                                                                               |
| --------------------- | -------- | -- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `status`              | `string` | —  | "open" / "investigating" / "escalated" / "closed" / "false\_positive"                                                                                                            |
| `source_surface`      | `string` | —  | "agent\_executor" / "llm\_gateway" / "agent\_worker"                                                                                                                             |
| `resolution_code`     | `string` | —  | "policy\_violation\_confirmed" / "no\_action\_required" / "escalated\_externally" / "detection\_error" / "benign\_context" / "test\_or\_synthetic" / "insufficient\_information" |
| `detection_type`      | `string` | —  | Detection type (a value in detectionTypes, for example "jailbreak\_attack" or "harmful\_content")                                                                                |
| `moderation_category` | `string` | —  | Harmful content category (a key in moderationCategories, for example "Hate", "Violence", or "Sexual")                                                                            |
| `shield_origin`       | `string` | —  | "userPrompt" / "documents" / "both" / "unknown"                                                                                                                                  |
| `policy_category`     | `string` | —  | Attack method category (a value of policyCategory)                                                                                                                               |

A value other than those above for status, source\_surface, resolution\_code, or shield\_origin returns 400. detection\_type, moderation\_category, and policy\_category accept any value, and an unknown value matches nothing.

These are records where Prompt Shield (prompt injection and jailbreak attempts) or Text Moderation (harmful content) detected a violation and execution was stopped. The detection surface (`sourceSurface`) is either AI agent execution (`agent_executor`) or the LLM Gateway (`llm_gateway`).

#### Request Example

**List guardrail alerts**

**curl**

```curl
curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/guardrail-alerts?limit=10&from=2026-08-01&to=2026-08-15" \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/guardrail-alerts",
  headers={"Authorization": f"Bearer {token}"},
  params={"limit": 10, "from": "2026-08-01", "to": "2026-08-15"},
)
```

**TypeScript**

```typescript
const params = new URLSearchParams({ limit: "10", from: "2026-08-01", to: "2026-08-15" });
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/guardrail-alerts?" + params,
{
  headers: { "Authorization": "Bearer " + accessToken },
}
);
```

**Go**

```go
req, _ := http.NewRequest("GET",
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/guardrail-alerts?limit=10&from=2026-08-01&to=2026-08-15",
  nil)
req.Header.Set("Authorization", "Bearer "+token)

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

#### Response Fields (200 OK)

| Field                                    | Type              | Description                                                                                                                                                                 |
| ---------------------------------------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `guardrailAlerts`                        | `array`           | Array of guardrail alert objects                                                                                                                                            |
| `guardrailAlerts[].guardrailAlertId`     | `string`          | Guardrail alert ID                                                                                                                                                          |
| `guardrailAlerts[].detectedAt`           | `string`          | Detection time (ISO 8601 format)                                                                                                                                            |
| `guardrailAlerts[].sourceSurface`        | `string`          | Detection surface (agent\_executor: during AI agent execution / llm\_gateway: via LLM Gateway / agent\_worker: inside the conversation pod)                                 |
| `guardrailAlerts[].detectionTypes`       | `array`           | Detection types (jailbreak\_attack: prompt injection / harmful\_content: harmful content)                                                                                   |
| `guardrailAlerts[].promptShieldOrigin`   | `object \| null`  | Where Prompt Shield detected the attack. Contains user\_prompt (the user input) and document\_indexes (positions in attached documents). Document contents are not included |
| `guardrailAlerts[].moderationCategories` | `object \| null`  | Severity per category. Hate / Sexual / SelfHarm / Violence on a four-level scale of 0, 2, 4, and 6                                                                          |
| `guardrailAlerts[].moderationThreshold`  | `integer \| null` | Threshold used for the decision                                                                                                                                             |
| `guardrailAlerts[].policyOutcome`        | `string`          | Policy outcome. Currently only blocked (execution stopped)                                                                                                                  |
| `guardrailAlerts[].policyCategory`       | `string \| null`  | Attack method category (for example prompt\_injection, system\_prompt\_extraction, or credential\_request). null for a detection without this category                      |
| `guardrailAlerts[].responseTemplateCode` | `string \| null`  | Code of the canned response returned to the user                                                                                                                            |
| `guardrailAlerts[].status`               | `string`          | Triage status (open: not yet handled / investigating: investigating / escalated: escalated / closed: resolved / false\_positive: false detection)                           |
| `guardrailAlerts[].resolutionCode`       | `string \| null`  | Resolution code                                                                                                                                                             |
| `guardrailAlerts[].resolvedAt`           | `string \| null`  | Resolution time (ISO 8601 format)                                                                                                                                           |
| `guardrailAlerts[].resolvedBy`           | `string \| null`  | User ID of the administrator who resolved the alert                                                                                                                         |
| `guardrailAlerts[].createdAt`            | `string`          | Creation time (ISO 8601 format)                                                                                                                                             |
| `guardrailAlerts[].updatedAt`            | `string`          | Update time (ISO 8601 format)                                                                                                                                               |
| `total`                                  | `integer`         | Total number of records                                                                                                                                                     |
| `limit`                                  | `integer`         | Number of items fetched                                                                                                                                                     |
| `page`                                   | `integer`         | Page number                                                                                                                                                                 |
| `hasMore`                                | `boolean`         | Whether a next page exists                                                                                                                                                  |

> **About the users who triggered detections**
>
> This API does not return information that identifies the user who triggered a detection (user ID, conversation ID, or message ID). It is intended for reviewing guardrail quality and tracking the status of safety responses, and cannot be used to trace the behavior of individual users.
>
> In addition, detections of `SelfHarm` alone are not recorded as alerts.

##### Response Example (200 OK)

```json
{
  "guardrailAlerts": [
    {
      "guardrailAlertId": "1f2e3d4c-5b6a-4789-8c9d-0e1f2a3b4c5d",
      "detectedAt": "2026-08-13T02:10:00.000Z",
      "sourceSurface": "agent_executor",
      "detectionTypes": ["harmful_content"],
      "promptShieldOrigin": null,
      "moderationCategories": {
        "Hate": 4,
        "Sexual": 0,
        "SelfHarm": 0,
        "Violence": 0
      },
      "moderationThreshold": 2,
      "policyOutcome": "blocked",
      "responseTemplateCode": null,
      "status": "open",
      "resolutionCode": null,
      "resolvedAt": null,
      "resolvedBy": null,
      "createdAt": "2026-08-13T02:10:00.100Z",
      "updatedAt": "2026-08-13T02:10:00.100Z"
    },
    {
      "guardrailAlertId": "2a3b4c5d-6e7f-4890-9a1b-2c3d4e5f6a7b",
      "detectedAt": "2026-08-12T09:32:11.000Z",
      "sourceSurface": "llm_gateway",
      "detectionTypes": ["jailbreak_attack"],
      "promptShieldOrigin": {
        "user_prompt": true,
        "document_indexes": []
      },
      "moderationCategories": null,
      "moderationThreshold": null,
      "policyOutcome": "blocked",
      "responseTemplateCode": null,
      "status": "closed",
      "resolutionCode": "policy_violation_confirmed",
      "resolvedAt": "2026-08-12T11:05:00.000Z",
      "resolvedBy": "8f14e45f-ceea-4d3c-9b2a-1a2b3c4d5e6f",
      "createdAt": "2026-08-12T09:32:11.050Z",
      "updatedAt": "2026-08-12T11:05:00.000Z"
    }
  ],
  "total": 14,
  "limit": 2,
  "page": 1,
  "hasMore": true
}
```

## Master Data Management SaaS

CRUD operations for organizations and job types. Unlike the read-only master data endpoints (`/v1/organizations`, `/v1/job-types`), creation, updates, and deletion require `master:manage` scope.

### Endpoint List

| メソッド   | エンドポイント                               | 説明                      | スコープ            |
| ------ | ------------------------------------- | ----------------------- | --------------- |
| GET    | `/v1/admin/organizations`             | List organizations      | `master:manage` |
| POST   | `/v1/admin/organizations`             | Create organization     | `master:manage` |
| GET    | `/v1/admin/organizations/:identifier` | Get organization detail | `master:manage` |
| PATCH  | `/v1/admin/organizations/:identifier` | Update organization     | `master:manage` |
| DELETE | `/v1/admin/organizations/:identifier` | Delete organization     | `master:manage` |
| GET    | `/v1/admin/job-types`                 | List job types          | `master:manage` |
| POST   | `/v1/admin/job-types`                 | Create job type         | `master:manage` |
| GET    | `/v1/admin/job-types/:identifier`     | Get job type detail     | `master:manage` |
| PATCH  | `/v1/admin/job-types/:identifier`     | Update job type         | `master:manage` |
| DELETE | `/v1/admin/job-types/:identifier`     | Delete job type         | `master:manage` |

### GET`/v1/admin/organizations`

List organizations. Fetches all records (no pagination).

#### Request Example

**List organizations (admin)**

**curl**

```curl
curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/organizations \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/organizations",
  headers={"Authorization": f"Bearer {token}"},
)

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

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/organizations",
{
  headers: { "Authorization": "Bearer " + accessToken },
}
);

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

**Go**

```go
req, _ := http.NewRequest("GET",
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/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[].code`         | `string`  | Organization code                     |
| `organizations[].name`         | `string`  | Organization name                     |
| `organizations[].displayOrder` | `integer` | Display order                         |
| `organizations[].isActive`     | `boolean` | Enabled/disabled                      |
| `organizations[].createdAt`    | `string`  | Creation date and time                |
| `organizations[].updatedAt`    | `string`  | Last updated date and time            |
| `hasMore`                      | `boolean` | Always false (all items are returned) |

##### Example Response (200 OK)

```json
{
  "organizations": [
    {
      "code": "sample_org",
      "name": "Sample Organization",
      "displayOrder": 0,
      "isActive": true,
      "createdAt": "2025-12-12T10:40:45.220Z",
      "updatedAt": "2026-04-13T01:21:57.695Z"
    },
    {
      "code": "sales",
      "name": "Sales Division",
      "displayOrder": 1,
      "isActive": true,
      "createdAt": "2025-12-24T19:26:37.000Z",
      "updatedAt": "2025-12-24T19:26:37.000Z"
    },
    {
      "code": "engineering",
      "name": "Engineering Division",
      "displayOrder": 2,
      "isActive": true,
      "createdAt": "2025-12-24T19:26:37.000Z",
      "updatedAt": "2025-12-24T19:26:37.000Z"
    },
    {
      "code": "other",
      "name": "Other",
      "displayOrder": -1,
      "isActive": false,
      "createdAt": "2025-12-24T19:26:38.000Z",
      "updatedAt": "2026-01-17T19:08:21.630Z"
    }
  ],
  "hasMore": false
}
```

#### Error Responses

| Status | Description                    |
| ------ | ------------------------------ |
| `403`  | master:manage scope is missing |

### POST`/v1/admin/organizations`

Create an organization.

#### Request Body

| パラメータ          | 型         | 必須 | 説明                                                                                                                                                  |
| -------------- | --------- | -- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `code`         | `string`  | 必須 | Organization code (unique). Lowercase letters, digits, and underscores (\`\_\`) only, up to 255 characters. Leading and trailing spaces are removed |
| `name`         | `string`  | 必須 | Organization name (up to 255 characters)                                                                                                            |
| `displayOrder` | `integer` | —  | Display order. If omitted, it is the largest positive display order plus 1 (when \`code\` is \`other\` it is -1, which displays the item last)      |
| `isActive`     | `boolean` | —  | Enabled/disabled (default: true)                                                                                                                    |

#### Request Example

**Create organization**

**curl**

```curl
curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/organizations \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
  "code": "marketing",
  "name": "Marketing Division",
  "displayOrder": 3,
  "isActive": true
}'
```

**Python**

```python
import requests

response = requests.post(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/organizations",
  headers={"Authorization": f"Bearer {token}"},
  json={'code': 'marketing', 'name': 'Marketing Division', 'displayOrder': 3, 'isActive': True},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/organizations",
{
  method: "POST",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"code": "marketing", "name": "Marketing Division", "displayOrder": 3, "isActive": true}),
}
);

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

**Go**

```go
payload := []byte(`{"code": "marketing", "name": "Marketing Division", "displayOrder": 3, "isActive": true}`)
req, _ := http.NewRequest("POST", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/organizations", bytes.NewBuffer(payload))
req.Header.Set("Content-Type", "application/json")
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)
```

##### Example Response (201 Created)

```json
{
  "code": "marketing",
  "name": "Marketing Division",
  "displayOrder": 3,
  "isActive": true,
  "createdAt": "2026-04-19T02:15:32.000Z",
  "updatedAt": "2026-04-19T02:15:32.000Z"
}
```

#### Error Responses

| Status | Description                                                                                                                                                                                                                                                                                                                                                               |
| ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | The request body is invalid (`code` / `name` is missing, `code` or `name` is not a string, `isActive` is not a boolean, `displayOrder` is not an integer, `code` contains characters other than lowercase letters, digits, and underscores, `code` or `name` exceeds 255 characters, the body is malformed JSON or not a JSON object (`code: "invalid_body"`), and so on) |
| `415`  | The body Content-Type is not application/json (`code: "unsupported_media_type"`)                                                                                                                                                                                                                                                                                          |
| `403`  | master:manage scope is missing                                                                                                                                                                                                                                                                                                                                            |
| `409`  | An organization with the same `code` already exists                                                                                                                                                                                                                                                                                                                       |

### GET`/v1/admin/organizations/:identifier`

Get organization detail. Can be specified by UUID or organization code.

#### Path Parameters

| パラメータ        | 型        | 必須 | 説明                                     |
| ------------ | -------- | -- | -------------------------------------- |
| `identifier` | `string` | 必須 | Organization UUID or organization code |

#### Request Example

**Get organization**

**curl**

```curl
curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/organizations/sales \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  f"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/organizations/{identifier}",
  headers={"Authorization": f"Bearer {token}"},
)
```

**TypeScript**

```typescript
const response = await fetch(
`https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/organizations/${identifier}`,
{
  headers: { "Authorization": "Bearer " + accessToken },
}
);
```

**Go**

```go
req, _ := http.NewRequest("GET",
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/organizations/"+identifier,
  nil)
req.Header.Set("Authorization", "Bearer "+token)

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

##### Example Response (200 OK)

```json
{
  "code": "sales",
  "name": "Sales Division",
  "displayOrder": 1,
  "isActive": true,
  "createdAt": "2025-12-24T19:26:37.000Z",
  "updatedAt": "2025-12-24T19:26:37.000Z"
}
```

#### Error Responses

| Status | Description                             |
| ------ | --------------------------------------- |
| `403`  | master:manage scope is missing          |
| `404`  | The specified organization is not found |

### PATCH`/v1/admin/organizations/:identifier`

Update an organization. Only `name` and `isActive` can be updated.

#### Path Parameters

| パラメータ        | 型        | 必須 | 説明                                     |
| ------------ | -------- | -- | -------------------------------------- |
| `identifier` | `string` | 必須 | Organization UUID or organization code |

#### Request Body

| パラメータ      | 型         | 必須 | 説明                |
| ---------- | --------- | -- | ----------------- |
| `name`     | `string`  | —  | Organization name |
| `isActive` | `boolean` | —  | Enabled/disabled  |

#### Request Example

**Update organization**

**curl**

```curl
curl -X PATCH https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/organizations/sales \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
  "name": "Sales Division",
  "isActive": true
}'
```

**Python**

```python
import requests

response = requests.patch(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/organizations/sales",
  headers={"Authorization": f"Bearer {token}"},
  json={'name': 'Sales Division', 'isActive': True},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/organizations/sales",
{
  method: "PATCH",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"name": "Sales Division", "isActive": true}),
}
);

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

**Go**

```go
payload := []byte(`{"name": "Sales Division", "isActive": true}`)
req, _ := http.NewRequest("PATCH", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/organizations/sales", bytes.NewBuffer(payload))
req.Header.Set("Content-Type", "application/json")
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)
```

##### Example Response (200 OK)

```json
{
  "code": "sales",
  "name": "Sales Division",
  "displayOrder": 1,
  "isActive": true,
  "createdAt": "2025-12-24T19:26:37.000Z",
  "updatedAt": "2026-04-19T02:18:40.000Z"
}
```

#### Error Responses

| Status | Description                                                                                                                                                                                                                                                                            |
| ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | Invalid request body (`name` exceeds 255 characters, neither `name` nor `isActive` provided, `name` is not a string or `isActive` is not a boolean, the body is malformed JSON or not a JSON object (`code: "invalid_body"`), etc.). Fields other than `name` / `isActive` are ignored |
| `415`  | The body Content-Type is not application/json (`code: "unsupported_media_type"`)                                                                                                                                                                                                       |
| `403`  | master:manage scope is missing                                                                                                                                                                                                                                                         |
| `404`  | The specified organization was not found                                                                                                                                                                                                                                               |

### DELETE`/v1/admin/organizations/:identifier`

Delete an organization.

#### Path Parameters

| パラメータ        | 型        | 必須 | 説明                                     |
| ------------ | -------- | -- | -------------------------------------- |
| `identifier` | `string` | 必須 | Organization UUID or organization code |

#### Request Example

**Delete organization**

**curl**

```curl
curl -X DELETE https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/organizations/sales \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.delete(
  f"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/organizations/{identifier}",
  headers={"Authorization": f"Bearer {token}"},
)
```

**TypeScript**

```typescript
const response = await fetch(
`https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/organizations/${identifier}`,
{
  method: "DELETE",
  headers: { "Authorization": "Bearer " + accessToken },
}
);
```

**Go**

```go
req, _ := http.NewRequest("DELETE",
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/organizations/"+identifier,
  nil)
req.Header.Set("Authorization", "Bearer "+token)

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

##### Response Example (200 OK)

```json
{ "code": "sales", "deleted": true }
```

| Field     | Type      | Description                                                                   |
| --------- | --------- | ----------------------------------------------------------------------------- |
| `code`    | `string`  | The deleted organization code (returns the path parameter `identifier` as-is) |
| `deleted` | `boolean` | Always `true`                                                                 |

#### Error Responses

| Status | Description                              |
| ------ | ---------------------------------------- |
| `403`  | master:manage scope is missing           |
| `404`  | The specified organization was not found |

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

List job types. Fetches all records (no pagination). Response fields have the same structure as the organizations list (organizations → jobTypes, organization code → job type code).

#### Request Example

**List job types**

**curl**

```curl
curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/job-types \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/job-types",
  headers={"Authorization": f"Bearer {token}"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/job-types",
{
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

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

**Go**

```go
req, _ := http.NewRequest("GET", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/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[].code`         | `string`  | Job type code                         |
| `jobTypes[].name`         | `string`  | Job type name                         |
| `jobTypes[].displayOrder` | `integer` | Display order                         |
| `jobTypes[].isActive`     | `boolean` | Enabled/disabled                      |
| `jobTypes[].createdAt`    | `string`  | Creation date and time                |
| `jobTypes[].updatedAt`    | `string`  | Last updated date and time            |
| `hasMore`                 | `boolean` | Always false (all items are returned) |

##### Example Response (200 OK)

```json
{
  "jobTypes": [
    {
      "code": "engineer",
      "name": "Engineer",
      "displayOrder": 1,
      "isActive": true,
      "createdAt": "2025-12-24T19:26:37.000Z",
      "updatedAt": "2025-12-24T19:26:37.000Z"
    },
    {
      "code": "sales",
      "name": "Sales",
      "displayOrder": 2,
      "isActive": true,
      "createdAt": "2025-12-24T19:26:37.000Z",
      "updatedAt": "2025-12-24T19:26:37.000Z"
    },
    {
      "code": "other",
      "name": "Other",
      "displayOrder": -1,
      "isActive": false,
      "createdAt": "2025-12-24T19:26:38.000Z",
      "updatedAt": "2026-01-17T19:08:21.630Z"
    }
  ],
  "hasMore": false
}
```

#### Error Responses

| Status | Description                    |
| ------ | ------------------------------ |
| `403`  | master:manage scope is missing |

### POST`/v1/admin/job-types`

Create a job type. The request body has the same structure as organization creation.

#### Request Example

**Create job type**

**curl**

```curl
curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/job-types \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
  "code": "manager",
  "name": "Manager",
  "displayOrder": 3,
  "isActive": true
}'
```

**Python**

```python
import requests

response = requests.post(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/job-types",
  headers={"Authorization": f"Bearer {token}"},
  json={'code': 'manager', 'name': 'Manager', 'displayOrder': 3, 'isActive': True},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/job-types",
{
  method: "POST",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"code": "manager", "name": "Manager", "displayOrder": 3, "isActive": true}),
}
);

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

**Go**

```go
payload := []byte(`{"code": "manager", "name": "Manager", "displayOrder": 3, "isActive": true}`)
req, _ := http.NewRequest("POST", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/job-types", bytes.NewBuffer(payload))
req.Header.Set("Content-Type", "application/json")
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)
```

##### Example Response (201 Created)

```json
{
  "code": "manager",
  "name": "Manager",
  "displayOrder": 3,
  "isActive": true,
  "createdAt": "2026-04-19T02:20:15.000Z",
  "updatedAt": "2026-04-19T02:20:15.000Z"
}
```

#### Error Responses

| Status | Description                                                                                                                                                                                                                                                                                                                                                               |
| ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | The request body is invalid (`code` / `name` is missing, `code` or `name` is not a string, `isActive` is not a boolean, `displayOrder` is not an integer, `code` contains characters other than lowercase letters, digits, and underscores, `code` or `name` exceeds 255 characters, the body is malformed JSON or not a JSON object (`code: "invalid_body"`), and so on) |
| `415`  | The body Content-Type is not application/json (`code: "unsupported_media_type"`)                                                                                                                                                                                                                                                                                          |
| `403`  | master:manage scope is missing                                                                                                                                                                                                                                                                                                                                            |
| `409`  | A job type with the same `code` already exists                                                                                                                                                                                                                                                                                                                            |

### GET`/v1/admin/job-types/:identifier`

Get job type detail. Can be specified by UUID or job type code.

#### Path Parameters

| パラメータ        | 型        | 必須 | 説明                             |
| ------------ | -------- | -- | ------------------------------ |
| `identifier` | `string` | 必須 | Job type UUID or job type code |

#### Request Example

**Get job type**

**curl**

```curl
curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/job-types/engineer \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  f"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/job-types/{identifier}",
  headers={"Authorization": f"Bearer {token}"},
)
```

**TypeScript**

```typescript
const response = await fetch(
`https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/job-types/${identifier}`,
{
  headers: { "Authorization": "Bearer " + accessToken },
}
);
```

**Go**

```go
req, _ := http.NewRequest("GET",
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/job-types/"+identifier,
  nil)
req.Header.Set("Authorization", "Bearer "+token)

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

##### Example Response (200 OK)

```json
{
  "code": "engineer",
  "name": "Engineer",
  "displayOrder": 1,
  "isActive": true,
  "createdAt": "2025-12-24T19:26:37.000Z",
  "updatedAt": "2025-12-24T19:26:37.000Z"
}
```

#### Error Responses

| Status | Description                    |
| ------ | ------------------------------ |
| `403`  | master:manage scope is missing |
| `404`  | Job type not found             |

### PATCH`/v1/admin/job-types/:identifier`

Update a job type. Only `name` and `isActive` can be updated.

#### Path Parameters

| パラメータ        | 型        | 必須 | 説明                             |
| ------------ | -------- | -- | ------------------------------ |
| `identifier` | `string` | 必須 | Job type UUID or job type code |

#### Request Body

| パラメータ      | 型         | 必須 | 説明              |
| ---------- | --------- | -- | --------------- |
| `name`     | `string`  | —  | Job type name   |
| `isActive` | `boolean` | —  | Active/Inactive |

#### Request Example

**Update job type**

**curl**

```curl
curl -X PATCH https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/job-types/engineer \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{"name": "Senior Engineer", "isActive": true}'
```

**Python**

```python
import requests

response = requests.patch(
  f"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/job-types/{identifier}",
  headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"},
  json={"name": "Senior Engineer", "isActive": True},
)
```

**TypeScript**

```typescript
const response = await fetch(
`https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/job-types/${identifier}`,
{
  method: "PATCH",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ name: "Senior Engineer", isActive: true }),
}
);
```

**Go**

```go
body, _ := json.Marshal(map[string]interface{}{"name": "Senior Engineer", "isActive": true})
req, _ := http.NewRequest("PATCH",
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/job-types/"+identifier,
  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()
```

##### Example Response (200 OK)

```json
{
  "code": "engineer",
  "name": "Senior Engineer",
  "displayOrder": 1,
  "isActive": true,
  "createdAt": "2025-12-24T19:26:37.000Z",
  "updatedAt": "2026-04-19T02:22:55.000Z"
}
```

#### Error Responses

| Status | Description                                                                                                                                                                                                                                                                            |
| ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | Invalid request body (`name` exceeds 255 characters, neither `name` nor `isActive` provided, `name` is not a string or `isActive` is not a boolean, the body is malformed JSON or not a JSON object (`code: "invalid_body"`), etc.). Fields other than `name` / `isActive` are ignored |
| `415`  | The body Content-Type is not application/json (`code: "unsupported_media_type"`)                                                                                                                                                                                                       |
| `403`  | master:manage scope is missing                                                                                                                                                                                                                                                         |
| `404`  | The specified job type was not found                                                                                                                                                                                                                                                   |

### DELETE`/v1/admin/job-types/:identifier`

Delete a job type. The response structure is the same as organization deletion.

#### Path Parameters

| パラメータ        | 型        | 必須 | 説明                             |
| ------------ | -------- | -- | ------------------------------ |
| `identifier` | `string` | 必須 | Job type UUID or job type code |

#### Request Example

**Delete job type**

**curl**

```curl
curl -X DELETE https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/job-types/engineer \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.delete(
  f"https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/job-types/{identifier}",
  headers={"Authorization": f"Bearer {token}"},
)
```

**TypeScript**

```typescript
const response = await fetch(
`https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/job-types/${identifier}`,
{
  method: "DELETE",
  headers: { "Authorization": "Bearer " + accessToken },
}
);
```

**Go**

```go
req, _ := http.NewRequest("DELETE",
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/admin/job-types/"+identifier,
  nil)
req.Header.Set("Authorization", "Bearer "+token)

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

##### Example Response (200 OK)

```json
{ "code": "engineer", "deleted": true }
```

#### Error Responses

| Status | Description                          |
| ------ | ------------------------------------ |
| `403`  | master:manage scope is missing       |
| `404`  | The specified job type was not found |

## Projects SaaS

This section covers calls made with a system integration token (Client Credentials flow). For calls made with an application token (Authorization Code flow), see [User API Reference (Projects)](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/reference/api-reference-projects.md).

A project is the unit in which multiple agents are placed to carry out work. From an external system you can list projects, start a run<!-- -->, and check run status<!-- -->.

There are two project types, and each is triggered differently.

| Type       | Description                                                                                           | How runs are triggered                                    |
| ---------- | ----------------------------------------------------------------------------------------------------- | --------------------------------------------------------- |
| `workflow` | Advances through steps in order. A run starts from the first enabled step.                            | `POST /v1/projects/{projectId}/runs`                      |
| `cycle`    | Keeps multiple agents running on their own schedules. An external event can add one extra ad-hoc run. | `POST /v1/projects/{projectId}/triggers/{triggerId}/fire` |

> **What you can operate on**
>
> The projects you can operate on are limited to the project restriction configured in Console ([Console Guide — Configuring project restrictions](https://developers.fd.agenticstar.tm.softbank.jp/en/docs/saas/api/agent/guide/console-guide.md#project-restriction)). Specifying a project ID outside that range returns the same `404 Not Found` as a project that does not exist. A system integration token can call only the five project API endpoints listed here. Calling any other project API returns `403 Forbidden` (`forbidden`).

### Endpoints

| メソッド | エンドポイント                                              | 説明                                | Scope (SaaS)   |
| ---- | ---------------------------------------------------- | --------------------------------- | -------------- |
| GET  | `/v1/projects`                                       | List projects                     | `project:read` |
| POST | `/v1/projects/{projectId}/runs`                      | Start a project run               | `project:run`  |
| POST | `/v1/projects/{projectId}/triggers/{triggerId}/fire` | Fire a trigger for one ad-hoc run | `project:run`  |
| GET  | `/v1/projects/{projectId}/runs/{runId}`              | Get run status                    | `project:read` |
| POST | `/v1/projects/{projectId}/runs/{runId}/cancel`       | Cancel a workflow run             | `project:run`  |

### GET`/v1/projects`

Retrieves the list of projects within the project restriction.<!-- --> Supports cursor-based pagination. `cycle` projects also appear in the list, but they are not valid targets for starting a run (`POST /v1/projects/{projectId}/runs`).

#### Query Parameters

| Parameter | Type      | Default | Description                                                            |
| --------- | --------- | ------- | ---------------------------------------------------------------------- |
| `limit`   | `integer` | `50`    | Number of items to retrieve (1-100)                                    |
| `cursor`  | `string`  | `—`     | Cursor for the next page (the cursor value from the previous response) |

Any other query parameter is ignored.<!-- --> my\_role can only be used with a user token, so it is ignored if specified.

<!-- -->

#### Request Example

**List projects**

**curl**

```curl
curl "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects?limit=20" \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects",
  headers={"Authorization": f"Bearer {token}"},
  params={"limit": "20"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects" + "?limit=20",
{
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

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

**Go**

```go
req, _ := http.NewRequest("GET", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects?limit=20", 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                                                                                            |
| ---------------------- | --------- | ------------------------------------------------------------------------------------------------------ |
| `projects`             | `array`   | Array of project objects                                                                               |
| `projects[].projectId` | `string`  | Project ID (UUID)                                                                                      |
| `projects[].name`      | `string`  | Project name                                                                                           |
| `projects[].type`      | `string`  | "workflow" or "cycle"                                                                                  |
| `projects[].status`    | `string`  | Project state. One of "active", "paused", "archived" or "admin\_stopped" (stopped by an administrator) |
| `projects[].tags`      | `array`   | Array of tags. An empty array when none are set                                                        |
| `hasMore`              | `boolean` | Whether a next page exists                                                                             |
| `cursor`               | `string`  | Cursor for the next page. Included only when hasMore is true                                           |

#### Response Example

<!-- -->

<!-- -->

```json
{
  "projects": [
    {
      "projectId": "550e8400-e29b-41d4-a716-446655440000",
      "name": "Order processing flow",
      "type": "workflow",
      "status": "active",
      "tags": []
    },
    {
      "projectId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "name": "Always-on inquiry handling",
      "type": "cycle",
      "status": "active",
      "tags": []
    }
  ],
  "hasMore": false
}
```

#### Error Responses

| Status | Description                                                                                                                                  |
| ------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | limit is outside 1-100 or cursor is invalid (code is invalid\_parameter)                                                                     |
| `403`  | The project:read scope is missing, or the project restriction is missing or invalid (code is insufficient\_scope or invalid\_project\_grant) |

### POST`/v1/projects/{projectId}/runs`

Starts a run of a `workflow` project. Calling it for a `cycle` project returns `409 Conflict` (`unsupported_project_type`).

#### Request Headers

| Header            | Required | Description                                                                                                 |
| ----------------- | -------- | ----------------------------------------------------------------------------------------------------------- |
| `Idempotency-Key` | Required | A duplicate-run prevention key issued by the caller. 8-128 characters using alphanumerics and \_ . : - only |

#### Path Parameters

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

#### Request Body

The body can be omitted. If you send one, make it a JSON object. <!-- -->Fields other than the one below are ignored, except that sending config returns 400 Bad Request (invalid\_parameter).

| パラメータ     | 型     | 必須 | 説明                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| --------- | ----- | -- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `payload` | `any` | —  | The request for the run. Any JSON value (an object, an array, a string, and so on) is accepted as is. It is converted to a JSON string and attached to the request to the agent of the first step (after a fork, the first step of each lane). The agent receives it as data from outside, not as instructions. Putting a file ID in the request does not attach the file. Omitted or null means no request. Up to 8,000 characters as a JSON string |

There are two limits. If `payload` exceeds 8,000 characters as a JSON string, `400 Bad Request` (`payload_too_large`) is returned. If the whole body exceeds 16 KiB, `413 Payload Too Large` (`body_too_large`) is returned.

<!-- -->

#### Response Fields (201 Created / 200 OK)

| Field      | Type       | Description                                                                                                       |
| ---------- | ---------- | ----------------------------------------------------------------------------------------------------------------- |
| `runId`    | `string`   | Run ID (UUID). Use it to retrieve run status                                                                      |
| `existing` | `boolean?` | true when an existing run was returned for a resend with the same Idempotency-Key. Not included on the first call |

The first call returns `201 Created`; a resend with the same `Idempotency-Key` returns `200 OK`.

#### Request Example

**Start run**

**curl**

```curl
curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs \
-H "Authorization: Bearer <access_token>" \
-H "Idempotency-Key: nightly-batch-20260917" \
-H "Content-Type: application/json" \
-d '{
  "payload": {
    "ticketId": "INC-1024",
    "summary": "Some users cannot log in"
  }
}'
```

**Python**

```python
import requests

response = requests.post(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs",
  headers={"Authorization": f"Bearer {token}", "Idempotency-Key": "nightly-batch-20260917"},
  json={'payload': {'ticketId': 'INC-1024', 'summary': 'Some users cannot log in'}},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs",
{
  method: "POST",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Idempotency-Key": "nightly-batch-20260917",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"payload": {"ticketId": "INC-1024", "summary": "Some users cannot log in"}}),
}
);

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

**Go**

```go
payload := []byte(`{"payload": {"ticketId": "INC-1024", "summary": "Some users cannot log in"}}`)
req, _ := http.NewRequest("POST", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs", bytes.NewBuffer(payload))
req.Header.Set("Content-Type", "application/json")
req.Header.Set("Authorization", "Bearer "+token)
req.Header.Set("Idempotency-Key", "nightly-batch-20260917")
resp, _ := http.DefaultClient.Do(req)
defer resp.Body.Close()

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

#### Response Example

```json
{
  "runId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}
```

> **How Idempotency-Key is handled**
>
> - Keys are matched per project. They do not expire.
> - Resending with the same key returns **the same run** even after the project has been paused, after the concurrent-run limit has been reached, or after that run has finished.
> - If a timeout leaves the outcome unknown, simply resend with the same key. Nothing is run twice.
> - To start a different run, always issue a new key.

Resending with the same key but a different `payload` returns `409 Conflict` (`origin_conflict`).

#### Error Responses

| Status | code                              | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| ------ | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | `idempotency_key_required`        | The Idempotency-Key header is missing                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `400`  | `idempotency_key_invalid`         | The Idempotency-Key length or character set is invalid                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `400`  | `invalid_parameter`               | projectId is not a UUID, or config is sent (this API does not accept it; param is config)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `400`  | `payload_too_large`               | payload exceeds 8,000 characters as a JSON string                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `400`  | `invalid_body`                    | The request body is malformed JSON or is not a JSON object                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `413`  | `body_too_large`                  | The request body exceeds 16 KiB                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `415`  | `unsupported_media_type`          | A request body is sent with a Content-Type other than application/json                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `403`  | `insufficient_scope`              | The project:run scope is missing                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `403`  | `invalid_project_grant`           | The project restriction is missing or invalid                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `404`  | `project_not_found`               | The project does not exist or is not accessible                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `400`  | `approvers_required`              | An enabled review step has no reviewers configured                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `409`  | `unsupported_project_type`        | A cycle project was specified                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `409`  | `project_inactive`                | The project is not active (paused or archived)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `409`  | `principal_suspended`             | An administrator has suspended the user the project runs as. Ask an administrator to transfer the project to another owner, or to lift the suspension                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `409`  | `start_step_in_branch_lane`       | The start step is in a lane of a branch step. Set the start step of the time trigger to a step outside the lanes of branch steps                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `409`  | `definition_pending`              | The first definition of the project is waiting for approval, so it cannot run yet. Start it after an approver (another owner or an administrator of the organization) approves it in the product screen                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `409`  | `relink_required`                 | The project cannot be started or resumed until the references that were not found during import are reconnected. The remaining references appear in the project's relink and in the placements' relink. To clear the references that refuse a start: for rows whose kind is "agent", place the agent again (POST /v1/projects/{projectId}/placements); for rows whose kind is "connector", save the connector again on the product screen; for the placements' relink (playbooks and skills that the placed agent points to but were not found), save the agent again with a spec (PATCH /v1/agents/{agentId}; an update that does not send spec does not clear them). Rows whose blocking is false are items to set up again if needed and do not refuse runs; they can be cleared with DELETE /v1/projects/{projectId}/relink, but clearing them alone does not make the project startable |
| `409`  | `branch_ai_unavailable`           | Branch steps that ask AI cannot run in this environment. Ask an administrator to set up the AI decision for branch steps, or disable those steps in the product screen, then start a new run                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `409`  | `automation_dlp_enabled`          | External automation steps cannot be saved or run while DLP integration is on. Ask an administrator to turn off DLP integration. Until then, a run can start only after the external automation steps are disabled or removed                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `409`  | `automation_destination_missing`  | The destination of the external automation step was not found. Set automationConfig.destinationId to an active destination from GET /v1/projects/automation-destinations with the API that updates the step, or disable the step. If no destinations are listed, ask an administrator                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `409`  | `automation_destination_inactive` | The destination of the external automation step is inactive. Ask an administrator to activate the destination, set automationConfig.destinationId to another active destination from GET /v1/projects/automation-destinations with the API that updates the step, or disable the step                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `409`  | `admin_stopped`                   | An administrator has stopped the project. Ask an administrator to resume it (this API cannot resume it)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `409`  | `unsupported_runtime`             | The project cannot run in this configuration, for example because agent runtimes are mixed                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `409`  | `origin_conflict`                 | A different payload was sent with the same Idempotency-Key                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `429`  | `too_many_active_runs`            | The project already has the maximum number of runs (3 in total) that are running or awaiting review                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |

### POST`/v1/projects/{projectId}/triggers/{triggerId}/fire`

Fires a webhook trigger configured on a `cycle` project and runs the target agent **once, as an extra ad-hoc run**. Calling it for a `workflow` project returns `404 Not Found`.

The scheduled runs stay exactly as configured. A fired run is added separately from the schedule. Where an earlier fire has not started running yet, however, a later fire **may be merged** into that run. Where it is, `jobId` returns the same value as the earlier fire, so the number of fires and the number of runs do not necessarily match.

#### Path Parameters

| パラメータ       | 型        | 必須 | 説明                               |
| ----------- | -------- | -- | -------------------------------- |
| `projectId` | `string` | 必須 | Project ID (UUID)                |
| `triggerId` | `string` | 必須 | ID of the trigger to fire (UUID) |

#### Request Body

| パラメータ     | 型        | 必須 | 説明                                                                                                                                                                                |
| --------- | -------- | -- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `eventId` | `string` | 必須 | A unique ID issued by the sender. Resending the same ID is treated as a duplicate. 1-160 characters using alphanumerics and \_ . : @ + - only                                     |
| `payload` | `any`    | —  | Arbitrary JSON passed to the agent. It is serialized to a JSON string and added to the request sent to the agent; anything beyond 8,000 characters after serialization is omitted |

#### Request Example

**Fire trigger**

**curl**

```curl
curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/triggers/d4e5f6a7-b8c9-4d0e-9f1a-2b3c4d5e6f70/fire \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
  "eventId": "order-20261118-0001",
  "payload": {
    "orderId": "A-1024"
  }
}'
```

**Python**

```python
import requests

response = requests.post(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/triggers/d4e5f6a7-b8c9-4d0e-9f1a-2b3c4d5e6f70/fire",
  headers={"Authorization": f"Bearer {token}"},
  json={'eventId': 'order-20261118-0001', 'payload': {'orderId': 'A-1024'}},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/triggers/d4e5f6a7-b8c9-4d0e-9f1a-2b3c4d5e6f70/fire",
{
  method: "POST",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"eventId": "order-20261118-0001", "payload": {"orderId": "A-1024"}}),
}
);

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

**Go**

```go
payload := []byte(`{"eventId": "order-20261118-0001", "payload": {"orderId": "A-1024"}}`)
req, _ := http.NewRequest("POST", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/triggers/d4e5f6a7-b8c9-4d0e-9f1a-2b3c4d5e6f70/fire", bytes.NewBuffer(payload))
req.Header.Set("Content-Type", "application/json")
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 (202 Accepted)

| Field    | Type     | Description                                                                                              |
| -------- | -------- | -------------------------------------------------------------------------------------------------------- |
| `result` | `string` | "accepted" (newly accepted) or "duplicate" (already accepted for the same eventId)                       |
| `jobId`  | `string` | ID of the receiving job. It cannot be used to get run status (GET /v1/projects/{projectId}/runs/{runId}) |

#### Response Example

<!-- -->

<!-- -->

```json
{
  "result": "accepted",
  "jobId": "9b2e4c61-0f3a-4a9b-9c1d-2f7e5a8b3c40"
}
```

> **What 202 means here**
>
> This `202 Accepted` means only that **the request was recorded as accepted**. The run happens afterwards, and its outcome is not part of this response. Do not treat `202` as business success.

#### Resending

Idempotency is decided by the combination of project, trigger, and `eventId`. Resending the same content returns `202` with `result: "duplicate"`. Sending the same `eventId` with a different `payload` returns `409 Conflict` (`event_conflict`).

#### Error Responses

| Status | code                     | Description                                                                                                                                                                                 |
| ------ | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | `invalid_event_id`       | eventId is missing or has an invalid format                                                                                                                                                 |
| `400`  | `invalid_parameter`      | projectId or triggerId is not a UUID                                                                                                                                                        |
| `400`  | `invalid_body`           | The request body is malformed JSON or is not a JSON object                                                                                                                                  |
| `415`  | `unsupported_media_type` | A request body is sent with a Content-Type other than application/json                                                                                                                      |
| `403`  | `insufficient_scope`     | The project:run scope is missing                                                                                                                                                            |
| `403`  | `invalid_project_grant`  | The project restriction is missing or invalid                                                                                                                                               |
| `404`  | `trigger_not_found`      | The project or trigger does not exist, is not accessible, the trigger is not a webhook trigger, or a workflow project was specified                                                         |
| `409`  | `trigger_disabled`       | The trigger is disabled                                                                                                                                                                     |
| `409`  | `project_not_active`     | The project is not in a runnable state                                                                                                                                                      |
| `409`  | `principal_suspended`    | An administrator has suspended the user the project runs as. Ask an administrator to transfer the project to another owner, or to lift the suspension                                       |
| `409`  | `admin_stopped`          | An administrator has stopped the project, or the Agent of the placement the trigger runs. Ask an administrator to resume it                                                                 |
| `409`  | `placement_unavailable`  | The target agent placement does not exist, no execution principal is configured, or the step of the placement is disabled (only a project owner can enable the step; enable it, then retry) |
| `409`  | `event_conflict`         | The same eventId was sent with a different payload                                                                                                                                          |
| `413`  | `body_too_large`         | The request body exceeds 16 KiB                                                                                                                                                             |

### GET`/v1/projects/{projectId}/runs/{runId}`

Retrieves the status of a run. Besides runs started through the API (`POST /v1/projects/{projectId}/runs`), runs started <!-- -->from the UI, by email, or on a schedule<!-- --> can also be retrieved. `cycle` projects do not create runs, so they are out of scope for this endpoint.

#### Path Parameters

| パラメータ       | 型        | 必須 | 説明                |
| ----------- | -------- | -- | ----------------- |
| `projectId` | `string` | 必須 | Project ID (UUID) |
| `runId`     | `string` | 必須 | Run ID (UUID)     |

#### Request Example

**Get run**

**curl**

```curl
curl https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13 \
-H "Authorization: Bearer <access_token>"
```

**Python**

```python
import requests

response = requests.get(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13",
  headers={"Authorization": f"Bearer {token}"},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13",
{
  headers: {
    "Authorization": "Bearer " + accessToken,
  },
}
);

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

**Go**

```go
req, _ := http.NewRequest("GET", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13", 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                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| --------------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `runId`                           | `string`         | Run ID (UUID)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `status`                          | `string`         | Run state. One of "running" (running), "waiting\_gate" (awaiting review), "closed\_done" (completed), "closed\_rejected" (ended by rejection), "closed\_failed" (ended by failure) or "cancelled" (cancelled). Any value other than "running" and "waiting\_gate" means the run has ended. However, when an owner or operator (including people with the organization operations role) resumes a "closed\_rejected" or "closed\_failed" run, the same run returns to "running" (endedAt also returns to null) |
| `originType`                      | `string \| null` | How the run started. One of "manual" (started from the UI), "api" (started through the API), "mail" (started by email) or "cron" (scheduled)                                                                                                                                                                                                                                                                                                                                                                  |
| `originRef`                       | `string \| null` | A reference value that depends on how the run started. For a run started through the API, the Idempotency-Key used to start it                                                                                                                                                                                                                                                                                                                                                                                |
| `currentStepId`                   | `string \| null` | ID (UUID) of the step in progress. While the run proceeds in separate lanes, the ID of the step before the branch. null for a completed run. For a run that ended for another reason, the ID of the step at that time may remain                                                                                                                                                                                                                                                                              |
| `startedByRef`                    | `string \| null` | Who or what started the run. See the "Who started the run" table below                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `actorLabel`                      | `string \| null` | Display name of a starter that is not a user (the system integration name or the sender address of an email). null otherwise                                                                                                                                                                                                                                                                                                                                                                                  |
| `startedAt`                       | `string \| null` | Start time (ISO 8601). null before it starts                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `endedAt`                         | `string \| null` | End time (ISO 8601). null before it ends. It returns to null when a closed run is resumed                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `summary`                         | `string \| null` | For a completed run, the output of the last completed step that recorded an output (first 2,000 characters). null if there is no such step and for a run that has not completed                                                                                                                                                                                                                                                                                                                               |
| `runtimeKind`                     | `string \| null` | Kind of runtime ("autonomous"). May be null for older runs                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `cancelRequestedAt`               | `string \| null` | Time (ISO 8601) when cancellation was requested. null if not requested                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `deadlineAt`                      | `string \| null` | Deadline of the workflow run (ISO 8601). null if it has no deadline                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `configRevision`                  | `number \| null` | Revision of the case configuration (Marketplace edition runs only). null for SaaS runs                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `steps`                           | `array`          | Records of the step runs, in the order they were recorded                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `steps[].runStepId`               | `string`         | ID of the step run (starts with "rs:")                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `steps[].stepId`                  | `string \| null` | Step ID (UUID)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `steps[].placementId`             | `string \| null` | ID (UUID) of the placement that handled the step. null for rows that do not run an agent (such as review steps)                                                                                                                                                                                                                                                                                                                                                                                               |
| `steps[].executionId`             | `string \| null` | ID of the agent execution. Set once the agent starts running. null for an external automation step                                                                                                                                                                                                                                                                                                                                                                                                            |
| `steps[].conversationId`          | `string \| null` | ID of the conversation of the agent execution. Set once the agent starts running                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `steps[].status`                  | `string`         | One of "pending" (waiting to run), "running" (running), "waiting\_gate" (awaiting review), "done" (done), "failed" (failed) or "skipped" (skipped)                                                                                                                                                                                                                                                                                                                                                            |
| `steps[].attempt`                 | `number \| null` | Retry count within the same visit (starting at 1). It also increases when a closed run is resumed and when the Agent is relaunched after a connection confirmation is approved                                                                                                                                                                                                                                                                                                                                |
| `steps[].lane`                    | `string \| null` | ID of the lane the step belongs to. "main" for steps that are not in a separate lane                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `steps[].scheduledAt`             | `string \| null` | When the step has a scheduled time, the time (ISO 8601) this row waits for. null once it starts                                                                                                                                                                                                                                                                                                                                                                                                               |
| `steps[].startedAt`               | `string \| null` | Start time (ISO 8601)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `steps[].endedAt`                 | `string \| null` | End time (ISO 8601)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `steps[].outputSummary`           | `string \| null` | Summary of the step output                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `steps[].outcome`                 | `string \| null` | Result of the agent execution or of the send of an external automation step. One of "completed", "incomplete", "failed", "timeout", "stopped", "denied" or "skipped". null for rows without a result                                                                                                                                                                                                                                                                                                          |
| `steps[].reasonCode`              | `string \| null` | Reason code for the result. "branch\_undecided" when a branch could not decide and a person is asked to choose; "branch\_not\_selected" for a step in a lane the branch did not choose                                                                                                                                                                                                                                                                                                                        |
| `steps[].held`                    | `boolean`        | Whether the step is held because the project is paused and is waiting to resume                                                                                                                                                                                                                                                                                                                                                                                                                               |
| `steps[].visit`                   | `number \| null` | Which visit to this step this is (increases with send-backs). null for rows without this record                                                                                                                                                                                                                                                                                                                                                                                                               |
| `steps[].reworkReason`            | `string \| null` | Reason for the send-back                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| `steps[].gateFor`                 | `string \| null` | For a review row, the step run (runStepId) it was raised for                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `steps[].routedFrom`              | `string \| null` | When steps were skipped by choosing a destination, the step run (runStepId) that chose it                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `steps[].late`                    | `string \| null` | Why a result that arrived late was not used to advance the run                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `steps[].gate`                    | `object \| null` | Summary of the review. Set on review step rows and on connection confirmation wait rows (gateKind is "connection"). null for other rows                                                                                                                                                                                                                                                                                                                                                                       |
| `steps[].gate.decision`           | `string \| null` | One of "proceed", "send\_back" or "reject". null if not decided yet                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `steps[].gate.waitSource`         | `string \| null` | What the review waits for. "human" (a person's decision) or "external" (an external condition)                                                                                                                                                                                                                                                                                                                                                                                                                |
| `steps[].resumeCommandId`         | `string \| null` | The commandId used when this row was started by resuming a closed run. It is set on the rows started by that resume (the step chosen and the other lanes started again). Otherwise null                                                                                                                                                                                                                                                                                                                       |
| `steps[].resumeReason`            | `string \| null` | The reason for resuming a closed run. It is set on the same rows as resumeCommandId. Otherwise null                                                                                                                                                                                                                                                                                                                                                                                                           |
| `steps[].supersededBy`            | `string \| null` | "resume" when a row left over from the previous round was closed by resuming a closed run. Otherwise null                                                                                                                                                                                                                                                                                                                                                                                                     |
| `steps[].gateKind`                | `string \| null` | "connection" for a connection confirmation wait row (a row created when the Agent stops before using a connector that requires human confirmation). null otherwise                                                                                                                                                                                                                                                                                                                                            |
| `steps[].connectionConfirmOf`     | `string \| null` | For a row relaunched after a connection confirmation is approved, the ID of that work item (workItemId). null otherwise                                                                                                                                                                                                                                                                                                                                                                                       |
| `steps[].handoff`                 | `object \| null` | The values and files this step's execution passed to the next step. null when the step has no values and file roles for the next step (outputConfig)                                                                                                                                                                                                                                                                                                                                                          |
| `steps[].handoff.values`          | `object`         | Value name → the returned text (up to 1,000 characters each)                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `steps[].handoff.files`           | `object`         | Role name → { filename } (the file name of the file with that role)                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `steps[].handoff.missing[]`       | `object[]`       | What did not arrive: name (the value or role name) and reason ("not\_returned" (the agent did not return it) / "file\_not\_found" (not among the output files))                                                                                                                                                                                                                                                                                                                                               |
| `steps[].handoff.truncated`       | `string[]`       | Names of values cut at 1,000 characters. \[] when none                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `plannedPlacements`               | `array`          | Order of steps and placements planned to run, based on the configuration when the run started                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `plannedPlacements[].stepId`      | `string \| null` | Step ID (UUID)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `plannedPlacements[].placementId` | `string \| null` | Placement ID (UUID). null for review steps and steps without an agent                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `lanes`                           | `array`          | Status of each lane after the branch. An empty array before the branch and for runs that do not use lanes                                                                                                                                                                                                                                                                                                                                                                                                     |
| `lanes[].laneId`                  | `string`         | Lane ID                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `lanes[].name`                    | `string \| null` | Lane name                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `lanes[].position`                | `number \| null` | Lane order (starting at 1)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `lanes[].state`                   | `string`         | One of "running" (running), "waiting\_gate" (awaiting review), "arrived" (waiting to join) or "closed" (ended)                                                                                                                                                                                                                                                                                                                                                                                                |
| `lanes[].currentStepId`           | `string \| null` | ID (UUID) of the step in progress in that lane. null for a lane waiting to join. For a lane that has ended, the ID of its last step may remain                                                                                                                                                                                                                                                                                                                                                                |
| `lanes[].arrived`                 | `boolean`        | Whether the lane has reached the join point                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |

The fields are the same regardless of the token used for the call (an application or a system integration).

##### Who started the run

| Started by                                                                    | startedByRef                                                                                                       | actorLabel                                       |
| ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------ |
| A user (from the UI, through the API, or by email sent from a member address) | User ID                                                                                                            | null                                             |
| A system integration                                                          | "client:" followed by the Client ID of the system integration. "system:federation-api" if the Client ID is unknown | Name of the system integration (null if unknown) |
| Email sent from an address that is not a member                               | "mail:" followed by a hash of the sender                                                                           | Sender address                                   |
| A schedule                                                                    | null                                                                                                               | null                                             |

For runs started by a system integration before 2026-09-25, `startedByRef` is null.

#### Response Example

<!-- -->

<!-- -->

```json
{
  "runId": "7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13",
  "status": "running",
  "originType": "api",
  "originRef": "nightly-batch-20260917",
  "currentStepId": "5d6e7f80-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
  "startedByRef": "bbbe4306-6975-420b-af47-fb4c8f48b4aa",
  "actorLabel": null,
  "startedAt": "2026-09-17T01:30:00.000Z",
  "endedAt": null,
  "summary": null,
  "runtimeKind": "autonomous",
  "cancelRequestedAt": null,
  "deadlineAt": null,
  "configRevision": null,
  "steps": [
    {
      "runStepId": "rs:1042",
      "stepId": "5d6e7f80-1a2b-4c3d-8e9f-0a1b2c3d4e5f",
      "placementId": "e4f5a6b7-c8d9-4e0f-a1b2-c3d4e5f6a7b8",
      "executionId": "6a7b8c9d-0e1f-4a2b-8c3d-4e5f6a7b8c9d",
      "conversationId": "9c8b7a6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d",
      "status": "running",
      "attempt": 1,
      "lane": "main",
      "scheduledAt": null,
      "startedAt": "2026-09-17T01:30:01.000Z",
      "endedAt": null,
      "outputSummary": null,
      "outcome": null,
      "reasonCode": null,
      "held": false,
      "visit": 1,
      "reworkReason": null,
      "gateFor": null,
      "routedFrom": null,
      "late": null,
      "gate": null,
      "resumeCommandId": null,
      "resumeReason": null,
      "supersededBy": null,
      "gateKind": null,
      "connectionConfirmOf": null,
      "handoff": null
    }
  ],
  "plannedPlacements": [
    { "stepId": "5d6e7f80-1a2b-4c3d-8e9f-0a1b2c3d4e5f", "placementId": "e4f5a6b7-c8d9-4e0f-a1b2-c3d4e5f6a7b8" },
    { "stepId": "c2f1a8e4-6b3d-4e7a-9c15-8d2e4f6a7b90", "placementId": null }
  ],
  "lanes": []
}
```

#### Error Responses

| Status | code                    | Description                                                              |
| ------ | ----------------------- | ------------------------------------------------------------------------ |
| `400`  | `invalid_parameter`     | projectId or runId is not a UUID                                         |
| `403`  | `insufficient_scope`    | The project:read scope is missing                                        |
| `403`  | `invalid_project_grant` | The project restriction is missing or invalid                            |
| `404`  | `run_not_found`         | The run does not exist, belongs to another project, or is not accessible |

### POST`/v1/projects/{projectId}/runs/{runId}/cancel`

Cancels a workflow run that is running or awaiting review (`status` is `"running"` or `"waiting_gate"`). This is the same as Cancel run on the screen.

When it is cancelled:

- The `status` of the workflow run becomes `"cancelled"` (cancelled).
  <!-- -->
  This cannot be undone, and the workflow run cannot be resumed (only workflow runs closed by a rejection or a failure can be resumed).
- <!-- -->
  Steps in progress are marked failed, and running Agents are told to stop.
  <!-- -->
- Review requests of review steps that have not been decided are withdrawn.

#### Path Parameters

| パラメータ       | 型        | 必須 | 説明                            |
| ----------- | -------- | -- | ----------------------------- |
| `projectId` | `string` | 必須 | Project ID (UUID)             |
| `runId`     | `string` | 必須 | ID of the workflow run (UUID) |

#### Request Body

| Field       | Type     | Required | Description                                                                        |
| ----------- | -------- | -------- | ---------------------------------------------------------------------------------- |
| `commandId` | `string` | Yes      | A value to identify resends (8 to 128 characters of letters, digits, and \_ . : -) |
| `reason`    | `string` | —        | The reason for canceling (up to 500 characters)                                    |

- If you send it for a workflow run that is not running (after it ended or was cancelled), nothing changes: `200 OK` is returned with `existing` set to `true`. The same applies when you resend after it was cancelled.
- If you send it around the same time as another cancel or the end of the workflow run, the choice between `202 Accepted` and `200 OK` and the value of `existing` may not match what actually happened. Check the result with `status` of Get a Workflow Run (`GET /v1/projects/{projectId}/runs/{runId}`).
- `504 Gateway Timeout` does not mean "it was not cancelled". Resend with the same `commandId`, or check `status` with Get a Workflow Run.

#### Request Example

**Cancel run**

**curl**

```curl
curl -X POST https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13/cancel \
-H "Authorization: Bearer <access_token>" \
-H "Content-Type: application/json" \
-d '{
  "commandId": "cancel-20261118-0001",
  "reason": "Because an error in the input data was noticed"
}'
```

**Python**

```python
import requests

response = requests.post(
  "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13/cancel",
  headers={"Authorization": f"Bearer {token}"},
  json={'commandId': 'cancel-20261118-0001', 'reason': 'Because an error in the input data was noticed'},
)

print(response.json())
```

**TypeScript**

```typescript
const response = await fetch(
"https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13/cancel",
{
  method: "POST",
  headers: {
    "Authorization": "Bearer " + accessToken,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"commandId": "cancel-20261118-0001", "reason": "Because an error in the input data was noticed"}),
}
);

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

**Go**

```go
payload := []byte(`{"commandId": "cancel-20261118-0001", "reason": "Because an error in the input data was noticed"}`)
req, _ := http.NewRequest("POST", "https://api.fd.agenticstar.tm.softbank.jp/api/v1/projects/3f2a9c1e-5b7d-4e8a-9c2f-1a6b4d8e0f31/runs/7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13/cancel", bytes.NewBuffer(payload))
req.Header.Set("Content-Type", "application/json")
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 (202 Accepted / 200 OK)

`202 Accepted` when this request cancelled the workflow run, and `200 OK` when it did not.

| Field               | Type             | Description                                                                                   |
| ------------------- | ---------------- | --------------------------------------------------------------------------------------------- |
| `runId`             | `string`         | ID of the workflow run                                                                        |
| `status`            | `string`         | The status of the workflow run after the request ("cancelled" when it was cancelled)          |
| `cancelRequestedAt` | `string \| null` | When the cancel was accepted (ISO 8601). null for a workflow run that was not cancelled       |
| `existing`          | `boolean`        | true when this request did not newly cancel the workflow run (always false with 202 Accepted) |

#### Response Example

```json
{
  "runId": "7c1d5e2a-8f3b-4a6c-b9d0-2e4f6a8c0b13",
  "status": "cancelled",
  "cancelRequestedAt": "2026-11-18T05:12:30.000Z",
  "existing": false
}
```

#### Error Responses

| Status | code                     | Description                                                                                                                              |
| ------ | ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | `invalid_parameter`      | projectId or runId is not a UUID, commandId is missing or has the wrong form, or reason is not a string or is longer than 500 characters |
| `400`  | `invalid_body`           | The body is malformed JSON or not a JSON object                                                                                          |
| `403`  | `insufficient_scope`     | The project:run scope is missing                                                                                                         |
| `403`  | `invalid_project_grant`  | The project restriction is missing or invalid                                                                                            |
| `404`  | `run_not_found`          | The workflow run does not exist, belongs to another project, or the project is not accessible                                            |
| `413`  | `body_too_large`         | The body exceeds 16 KiB                                                                                                                  |
| `415`  | `unsupported_media_type` | The Content-Type of the body is not application/json                                                                                     |

<!-- -->

<!-- -->

<!-- -->

### Notes on the Project API

| Item                          | Detail                                                                                                                                                                                                                                                                                                                                          |
| ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| What 404 means                | The same `404 Not Found` is returned whether the project does not exist or is not accessible, and the response does not reveal which of the two applies. The code is fixed per endpoint: `project_not_found` for starting a run, `trigger_not_found` for firing a trigger, and `run_not_found` for run status and for canceling a workflow run. |
| When the type is out of scope | Calling trigger fire on a `workflow` project, or run status or canceling a workflow run on a `cycle` project, returns `404`. Starting a run on a `cycle` project is the one exception: it returns `409 unsupported_project_type`.                                                                                                               |
| Request body                  | When you send a body, make it a JSON object. Anything other than `Content-Type: application/json` returns `415`, malformed JSON or a body that is not a JSON object returns `400` (`invalid_body`), and a body larger than 16 KiB returns `413`.                                                                                                |
| Unknown fields / queries      | Fields and query parameters that are not in the specification are ignored. An invalid value for a documented query parameter, or a `cursor` that cannot be read, returns `400 Bad Request`.                                                                                                                                                     |
| Timeouts                      | `504 Gateway Timeout` does not mean "it did not run". Resend a run start with the same `Idempotency-Key`, a trigger fire with the same `eventId` and the same body, and a workflow run cancel with the same `commandId`.                                                                                                                        |

## Error Responses

### HTTP Status Codes

HTTP status codes that may be returned by any endpoint.

| Status                       | Description                                             |
| ---------------------------- | ------------------------------------------------------- |
| `400 Bad Request`            | Invalid request parameters                              |
| `401 Unauthorized`           | Invalid or missing token                                |
| `403 Forbidden`              | Insufficient permissions to access the resource         |
| `404 Not Found`              | Resource not found                                      |
| `409 Conflict`               | Resource conflict (e.g., duplicate code)                |
| `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 exceeded                                     |
| `500 Internal Server Error`  | Internal server error                                   |
| `502 Bad Gateway`            | Communication error with an upstream service            |
| `503 Service Unavailable`    | Service temporarily unavailable                         |
| `504 Gateway Timeout`        | Upstream service response timeout                       |

### Error Response Format

All error responses are returned with the following common structure.

| Field                    | Type     | Description                                                                                                                                                                                                                                                    |
| ------------------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `error.type`             | `string` | Error category. 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", or "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 name that caused the error. Included only for validation errors                                                                                                                                                                                  |
| `error.suggested_action` | `string` | Recommended action to resolve the error. 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"
  }
}
```

### When the Request Is Stopped Before Reaching the API

If a layer in front of the API (such as a security inspection) returns an HTML error page, the response is replaced with JSON in the common format above. In that case, `error.code` is one of the following.

| Status                     | error.code           | Description                                                                                                                                                                                             |
| -------------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 403                        | `waf_blocked`        | The request was stopped by a security inspection in front of the API. If the request is legitimate, contact support with `error.reference` (or the `x-request-id` response header if it is not present) |
| 4xx and 5xx other than 403 | `upstream_api_error` | The request was rejected by, or caused an error in, a layer in front of the API. If this continues, contact support with `error.reference` (or the `x-request-id` response header if it is not present) |

| Field             | Type     | Description                                                                                                                            |
| ----------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `error.reference` | `string` | Reference number for a request stopped before reaching the API. Include it when contacting support. Omitted when no value is available |

```json
{
  "error": {
    "type": "forbidden_error",
    "message": "The request was blocked by a web application firewall before it reached the API.",
    "code": "waf_blocked",
    "suggested_action": "The request matched a firewall rule in front of the API. If the request is legitimate, contact support with the reference.",
    "reference": "20261018T012345Z-0123456789abcdef"
  }
}
```

## Automatically Recorded Management Operations SaaS

The following management operations automatically generate an audit log entry.

| Resource     | Operation                                                                       | action    |
| ------------ | ------------------------------------------------------------------------------- | --------- |
| User         | Create                                                                          | `create`  |
| User         | Change role (promote to admin)                                                  | `promote` |
| User         | Change role (demote to general)                                                 | `demote`  |
| User         | Approve                                                                         | `approve` |
| User         | Revoke approval                                                                 | `reject`  |
| User         | Delete                                                                          | `delete`  |
| Organization | Create                                                                          | `create`  |
| Organization | Update                                                                          | `update`  |
| Organization | Delete                                                                          | `delete`  |
| Job type     | Create                                                                          | `create`  |
| Job type     | Update                                                                          | `update`  |
| Job type     | Delete                                                                          | `delete`  |
| User         | Suspend, resume, and unlock (`meta.action` is `suspend`, `resume`, or `unlock`) | `update`  |
| User         | Change affiliation and job (`meta.action` is `update-affiliation`)              | `update`  |
