Admin API Reference

API reference for user management, log viewing, master data management, and shared memory search. For end-user-facing APIs (Chat / Conversations / Files / Search / User / MCP / A2A / public master data), see the User API Reference.

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.

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 and Authentication API Reference (SaaS).

Pagination

List retrieval endpoints support offset-based pagination.

Parameter	Type	Description
limit	integer	Number of items per page. 1 to 100 (default 25)
offset	integer	Number of items to skip. 0 or greater (default 0)

Responses include total, limit, offset, and hasMore. When hasMore is true, increase offset to offset + limit to retrieve the next page.

curl

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

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

Endpoints supporting offset-based pagination: users list, audit logs list, LLM logs list, and access logs list. Organization and job type lists do not support pagination and always return all records.

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

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

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
403	sharedmemory:query scope is missing
429	Monthly quota exceeded

User Management SaaS

List, delete, change role, approve, and revoke approval of users.

Endpoint List

メソッド	エンドポイント	説明	スコープ
GET	/v1/admin/users	List users	users:read / 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

GET/v1/admin/users

List users. Supports offset-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)
offset	integer	—	Offset (0 or more, default: 0)
role	string	—	Role filter. "admin" can be specified
is_approved	string	—	Approval status filter. "true" or "false"
search	string	—	Search string (max 100 characters). Searches by email address, etc.
organization	string	—	Organization code filter (max 50 characters; alphanumeric, hyphen, underscore)
job_type	string	—	Job type code filter (max 50 characters; alphanumeric, hyphen, underscore)

Request Example

List users

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

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", or "approved")
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
total	integer	Total count
limit	integer	Number of items fetched
offset	integer	Offset
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"
    },
    {
      "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"
    },
    {
      "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"
    }
  ],
  "total": 132,
  "limit": 3,
  "offset": 0,
  "hasMore": true
}

Error Response

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

DELETE/v1/admin/users/:userId

Delete a user. Requires users:manage scope.

Path Parameters

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

Request Example

Delete user

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

Response Example (200 OK)

JSON

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

Error Responses

Status	Description
400	Invalid request (userId missing, etc.)
404	The specified user was not found (including already deleted)

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

Change a user's role. Only approved users can have their role changed.

Path Parameters

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

Request Body

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

Request Example

Change user role

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

Response Example (200 OK)

JSON

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

Error Response

Status	Description
400	role is missing or invalid, or the target user is not approved
403	users:manage scope is missing
404	User not found

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

Approve a user. Only users with status "pending" can be approved.

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 Example

Approve user

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

Response Example (200 OK)

JSON

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

Error Responses

Status	Description
400	User status is not "pending" (cannot approve)
403	Missing users:manage scope
404	User not found

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

Revoke a user's approval. Only users with status "approved" can have their approval revoked. After revocation, the status returns to "pending".

note

When revocation succeeds, a notification email is automatically sent to the target user's email address.

Path Parameters

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

Request Example

Reject user

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

Response Example (200 OK)

JSON

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

Error Responses

Status	Description
400	User status is not "approved" (cannot revoke)
403	Missing users:manage scope
404	User not found

Logs SaaS

View audit logs, LLM logs, and access logs. All support offset-based pagination and date range filters.

Endpoint List

メソッド	エンドポイント	説明	スコープ
GET	/v1/admin/audit-logs	List audit logs	logs:read
GET	/v1/admin/llm-logs	List LLM logs	logs:read
GET	/v1/admin/access-logs	List access logs	logs:read

Common Query Parameters

パラメータ	型	必須	説明
limit	integer	—	Number of items to fetch (1–100, default: 25)
offset	integer	—	Offset (0 or more, default: 0)
from	string	—	Start date (YYYY-MM-DD format, UTC)
to	string	—	End date (YYYY-MM-DD format, UTC). Includes the end of the specified day

GET/v1/admin/audit-logs

List audit logs. Returned in descending order of creation date.

Request Example

List audit logs

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

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, etc.)
auditLogs[].meta	object | null	Additional metadata
auditLogs[].userId	string	User ID who performed the operation
auditLogs[].userEmail	string | null	Email address of the user
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
offset	integer	Offset
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",
      "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": "5f4e4fdf-14fe-4684-b6d1-aa4f3a8dabb9",
      "userEmail": "service-account-client@federation.invalid",
      "ipAddress": "::ffff:127.0.0.1",
      "userAgent": "Mozilla/5.0 (...)",
      "createdAt": "2026-04-19T05:04:19.876Z"
    },
    {
      "auditLogId": "f84ef377-9d75-4875-9958-b084c91a3c9b",
      "resource": "config/organizations/list",
      "action": "delete",
      "meta": {
        "id": "sales",
        "timestamp": "2026-04-19T05:02:01.729Z"
      },
      "userId": "5f4e4fdf-14fe-4684-b6d1-aa4f3a8dabb9",
      "userEmail": "service-account-client@federation.invalid",
      "ipAddress": "::ffff:127.0.0.1",
      "userAgent": "Mozilla/5.0 (...)",
      "createdAt": "2026-04-19T05:02:01.736Z"
    }
  ],
  "total": 1537,
  "limit": 3,
  "offset": 0,
  "hasMore": true
}

GET/v1/admin/llm-logs

List LLM logs. Returned in descending order of timestamp.

Request Example

List LLM logs

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

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[].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	Metadata (additional information)
llmLogs[].createdAt	string | null	Creation date and time
total	integer	Total count
limit	integer	Number of items fetched
offset	integer	Offset
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,
      "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,
      "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,
      "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,
  "offset": 0,
  "hasMore": true
}

GET/v1/admin/access-logs

List access logs. Returned in descending order of timestamp.

Request Example

List access logs

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

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
offset	integer	Offset
hasMore	boolean	Whether the next page exists

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,
  "offset": 0,
  "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)

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

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

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"
    }
  ]
}

Error Responses

Status	Description
403	master:manage scope is missing

POST/v1/admin/organizations

Create an organization.

Request Body

パラメータ	型	必須	説明
code	string	必須	Organization code (unique)
name	string	必須	Organization name
displayOrder	integer	—	Display order. If omitted, the item is appended to the end of existing items
isActive	boolean	—	Enabled/disabled (default: true)

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	Invalid request body (missing code / name, type mismatch, etc.)
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

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

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

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, no updatable fields provided, fields other than name / isActive included, etc.)
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

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

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).

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

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"
    }
  ]
}

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.

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	Invalid request body (missing code / name, type mismatch, etc.)
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

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

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

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

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, no updatable fields provided, fields other than name / isActive included, etc.)
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

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

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

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)
429 Too Many Requests	Rate limit exceeded
500 Internal Server Error	Internal server error

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", or "server_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"
  }
}

Automatically Recorded Management Operations SaaS

The following management operations automatically generate an audit log entry.

Resource	Operation	action
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