The full monolithic Soracom Platform OpenAPI spec — 487 operations across 40 tags covering every Soracom service surface (Sim, Subscriber, Group, Harvest, Inventory, Napter, EventHandler, VPG, Billing, Auth, Query, Lagoon, LoRaWAN, Sigfox, SoraCam, Batch). Source of truth maintained in the soracom-cli repo.
openapi: 3.0.0
info:
description: Soracom API v1
title: Soracom API
version: 20250903-043502
servers:
- description: Japan coverage production API endpoint
url: https://api.soracom.io/v1
- description: Global coverage production API endpoint
url: https://g.api.soracom.io/v1
paths:
/analysis/queries:
post:
description: Executes a SQL query asynchronously. You can check the status of
a SQL query execution with the [Analysis:getAnalysisQueries API](#/Analysis/getAnalysisQueries).
operationId: startAnalysisQueries
requestBody:
content:
application/json:
example:
from: 1743465600
sql: SELECT * FROM SIM_SESSION_EVENTS LIMIT 10
to: 1743552000
schema:
$ref: '#/components/schemas/StartAnalysisQueriesRequest'
description: A SQL query execution request.
required: true
responses:
"200":
content:
application/json:
example:
queryId: ffa91d0c371d45c4bf53d55ab5c14955
schema:
$ref: '#/components/schemas/StartAnalysisQueriesResponse'
description: A new SQL query execution has started.
security:
- api_key: []
api_token: []
summary: Execute a new SQL query asynchronously
tags:
- Analysis
x-soracom-cli:
- analysis queries start
/analysis/queries/{query_id}:
get:
description: Retrieve the execution status of a SQL query.
operationId: getAnalysisQueries
parameters:
- description: SQL query ID.
in: path
name: query_id
required: true
schema:
type: string
responses:
"200":
content:
application/json:
example:
columnInfo:
- databaseType: FIXED
name: ICCID
type: string
- databaseType: TEXT
name: IMEI
type: string
- databaseType: NUMBER
name: IMSI
type: number
fileSize: 12345678
rowCount: 12345
status: COMPLETED
url: https://soracom-analysis-export.s3.amazonaws.com/ffa91d0c-371d-45c4-bf53-d55ab5c14955.csv.gz
schema:
$ref: '#/components/schemas/GetAnalysisQueriesResponse'
description: The execution status, results, and download URL of the SQL
query.
security:
- api_key: []
api_token: []
summary: Retrieve the execution status of a SQL query
tags:
- Analysis
x-soracom-cli:
- analysis queries get
/analysis/schemas:
get:
description: |
Retrieves the available schemas and their column information within the database. You can use this information as a reference when converting data types of data retrieved with the [Analysis:startAnalysisQueries API](#/Analysis/startAnalysisQueries).
Example: If the column `type` is `string` as shown below, it can be treated as a string.
```json
{
"name": "SIM_SESSION_EVENTS",
"columnInfo": [
{
"name": "APN",
"type": "string",
"databaseType": "TEXT",
"description": "Access Point Name indicating the network gateway for the SIM session."
}
]
}
```
operationId: getAnalysisSchemas
responses:
"200":
content:
application/json:
example:
- columnInfo:
- databaseType: TEXT
description: Access Point Name indicating the network gateway for
the SIM session.
name: APN
type: string
- databaseType: TEXT
description: The primary DNS server IP address used during the SIM
session.
name: DNS0
type: string
- databaseType: TEXT
description: The secondary DNS server IP address used during the
SIM session.
name: DNS1
type: string
- databaseType: TEXT
description: Describes the type of event associated with the SIM
session, such as Created, Deleted, or Updated.
name: EVENT
type: string
- databaseType: TEXT
description: Home Public Land Mobile Network code that identifies
the home network operator.
name: HPLMN
type: string
- databaseType: TEXT
description: The Integrated Circuit Card Identifier, a unique number
assigned to the SIM card.
name: ICCID
type: string
name: SIM_SESSION_EVENTS
schema:
$ref: '#/components/schemas/GetAnalysisSchemasResponse'
description: A list of available database schemas and their column information.
security:
- api_key: []
api_token: []
summary: Retrieve available database schemas
tags:
- Analysis
x-soracom-cli:
- analysis schemas
/audit_logs/api:
get:
description: Retrieve audit logs for Soracom API calls.
operationId: getApiAuditLogs
parameters:
- description: Filter item for audit log retrieval by API kind (e.g. `/v1/auth`).
in: query
name: api_kind
required: false
schema:
type: string
- description: Start time for the log search range (unixtime milliseconds).
in: query
name: from_epoch_ms
required: false
schema:
type: integer
- description: End time for the log search range (unixtime milliseconds).
in: query
name: to_epoch_ms
required: false
schema:
type: integer
- description: Maximum number of log entries to retrieve (value range is 1 to
1000).
in: query
name: limit
required: false
schema:
maximum: 1000
minimum: 1
type: integer
- description: The value of `requestedTimeEpochMs` in the last log entry retrieved
in the previous page. By specifying this parameter, you can continue to
retrieve the list from the next page onward.
in: query
name: last_evaluated_key
required: false
schema:
type: string
responses:
"200":
content:
application/json:
example:
- apiKind: /v1/bills
operatorId: OPXXXXXXXXXX
remoteIpAddress: xxx.xxx.xxx.xxx
requestPath: /v1/bills
requestedTimeEpocMs: 1234567890123
statusCode: 200
userName: SORACOMAPI
schema:
items:
$ref: '#/components/schemas/APIAuditLogEntry'
type: array
description: A list of Soracom API audit log entries.
security:
- api_key: []
api_token: []
summary: Retrieve audit logs for Soracom API calls
tags:
- AuditLog
x-soracom-cli:
- audit-logs api get
x-soracom-cli-pagination:
request:
param: last_evaluated_key
response:
header: x-soracom-next-key
/audit_logs/napter:
get:
description: Retrieve audit logs for Soracom Napter.
operationId: getNapterAuditLogs
parameters:
- description: Type of the target resource to query log entries.
in: query
name: resource_type
required: false
schema:
enum:
- Subscriber
type: string
- description: Identity of the target resource to query log entries.
in: query
name: resource_id
required: false
schema:
type: string
- description: Start time for the log search range (unixtime milliseconds).
in: query
name: from
required: false
schema:
type: integer
- description: End time for the log search range (unixtime milliseconds).
in: query
name: to
required: false
schema:
type: integer
- description: Maximum number of log entries to retrieve (value range is 1 to
1000).
in: query
name: limit
required: false
schema:
maximum: 1000
minimum: 1
type: integer
- description: The value of `time` in the last log entry retrieved in the previous
page. By specifying this parameter, you can continue to retrieve the list
from the next page onward.
in: query
name: last_evaluated_key
required: false
schema:
type: string
responses:
"200":
content:
application/json:
example:
- connectionId: 12345678-abcd-1234-abcd-123456789010
createdAt: 1234567890123
direction:
destinationIPAddress: xxx.xxx.xxx.xxx
destinationPort: 22
sourceIPAddress: xxx.xxx.xxx.xxx
sourcePort: 51720
imsi: "123456789012345"
operatorId: OPXXXXXXXXXX
tls: false
type: CLOSED
- connectionId: 12345678-abcd-1234-abcd-123456789011
createdAt: 1234567890123
direction:
destinationIPAddress: xxx.xxx.xxx.xxx
destinationPort: 22
sourceIPAddress: xxx.xxx.xxx.xxx
sourcePort: 51720
imsi: "234567890123456"
operatorId: OPXXXXXXXXXX
tls: false
type: EXPIRED
schema:
items:
$ref: '#/components/schemas/NapterAuditLogEntry'
type: array
description: A list of Napter audit log entries.
security:
- api_key: []
api_token: []
summary: Retrieve audit logs for Soracom Napter
tags:
- AuditLog
x-soracom-cli:
- audit-logs napter get
x-soracom-cli-pagination:
request:
param: last_evaluated_key
response:
header: x-soracom-next-key
/auth:
post:
description: |
Performs authentication to access to the Soracom API. Please include the following information in your request.
- To perform authentication by a root account, specify `email` and `password`.
- To perform authentication by an AuthKey, specify `authKeyId` and `authKey`.
- To perform authentication by a SAM user, specify `operatorId`, `userName` and `password`.
An API key and API token will be included in the response if successful. Use the API key and API token to perform subsequent requests.
operationId: auth
requestBody:
content:
application/json:
examples:
To perform authentication by a SAM user:
value:
operatorId: OPXXXXXXXXXX
password: p@$$w0rd
userName: SORACOMAPI
To perform authentication by a root account:
value:
email: soracomapi@example.com
password: p@$$w0rd
To perform authentication by an AuthKeyId and AuthKey:
value:
authKey: secret-abcde12345fghij67890klmno12345pqrst67890uvwxy12345abcde67890fghi...
authKeyId: keyId-abcde12345fghij67890klmno12345pq
schema:
$ref: '#/components/schemas/AuthRequest'
description: Authentication request.
required: true
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/AuthResponse'
description: Authentication successful.
"401":
description: Authentication failed.
summary: Performs authentication to access to the Soracom API.
tags:
- Auth
x-soracom-cli:
- auth
/auth/logout:
post:
description: Revokes the API key and API token that was used to call this API.
Once revoked, the API key and API token cannot be used to make further requests
to the API, regardless of the key and token's original expiration time. This
API can be called regardless of any permission settings.
operationId: logout
responses:
"204":
description: Successfully revoked the API key and the API token.
security:
- api_key: []
api_token: []
summary: Revokes an API key and API token in order to remove access to the Soracom
API.
tags:
- Auth
x-soracom-cli:
- logout
/auth/password_reset_token/issue:
post:
description: Generates a password reset token and sends it to the operator's
primary email address. After receiving the password reset token, call /v1/auth/password_reset_token/verify
API with the token to update the operator's password.
operationId: issuePasswordResetToken
requestBody:
content:
application/json:
example:
email: soracomapi@example.com
schema:
$ref: '#/components/schemas/IssuePasswordResetTokenRequest'
description: email address
required: true
responses:
"200":
description: Password reset token successfully sent to the specified email
address.
"400":
description: Invalid email address.
summary: Issues a password reset token for the operator.
tags:
- Auth
x-soracom-cli:
- auth issue-password-reset-token
/auth/password_reset_token/verify:
post:
description: Updates the operator's password if the password reset token is
verified.
operationId: verifyPasswordResetToken
requestBody:
content:
application/json:
example:
password: p@$$w0rd
token: abcde12345fghij67890klmno12345pqrst67890uvwxy12345abcde67890fghi...
schema:
$ref: '#/components/schemas/VerifyPasswordResetTokenRequest'
description: token, password
required: true
responses:
"200":
description: Password successfully updated.
"400":
description: Invalid token.
"404":
description: Token expired.
summary: Verifies the password reset token and updates password.
tags:
- Auth
x-soracom-cli:
- auth verify-password-reset-token
/auth/switch_user:
post:
description: Using the API key and API token of the original user, call this
API to issue an API key and API token of the target user that you are switching
to. The original user should already be registered in the target user's trust
policy. See [User:updateUserTrustPolicy](#!/User/updateUserTrustPolicy) for
information on updating the trust policy.
operationId: switchUser
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SwitchUserRequest'
description: Specify the user to switch to and the validity period of the
API token to be issued.
required: true
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/AuthResponse'
description: Authentication successful.
"400":
description: Switch user not allowed.
security:
- api_key: []
api_token: []
summary: Generates an API key and an API token to call APIs as a different user.
tags:
- Auth
x-soracom-cli:
- auth switch-user
/batch_groups:
get:
description: Returns a list of batch groups.
operationId: listBatchGroups
parameters:
- description: Maximum number of batch groups to retrieve. The number of batch
groups returned may be less than the specified value.
example: 10
in: query
name: limit
required: false
schema:
format: int32
type: integer
- description: The value of the `x-soracom-next-key` header returned in the
response to the last request. Specify this to retrieve the next page of
batch groups.
in: query
name: last_evaluated_key
required: false
schema:
type: string
responses:
"200":
content:
application/json:
schema:
items:
$ref: '#/components/schemas/BatchGroupResponse'
type: array
description: A list of batch groups was retrieved successfully.
security:
- api_key: []
api_token: []
summary: List batch groups.
tags:
- Batch
x-soracom-cli:
- batch-groups list
x-soracom-cli-pagination:
request:
param: last_evaluated_key
response:
header: x-soracom-next-key
post:
description: |
Create a new batch group for organizing and managing batch jobs. To create a batch job, use the [Batch:createBatchJob](#/Batch/createBatchJob) instead.
operationId: createBatchGroup
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateBatchGroupRequest'
required: true
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/BatchGroupResponse'
description: The batch group has been created.
security:
- api_key: []
api_token: []
summary: Create batch group.
tags:
- Batch
x-soracom-cli:
- batch-groups create
/batch_groups/{batch_group_id}:
delete:
description: |
Delete the specified batch group. Batch groups can only be deleted if there are no running batch jobs in the group.
operationId: deleteBatchGroup
parameters:
- description: Batch group ID.
in: path
name: batch_group_id
required: true
schema:
type: string
responses:
"204":
description: The batch group has been deleted.
"400":
description: The batch group cannot be deleted because there are running
batch jobs.
"404":
description: Batch group not found.
security:
- api_key: []
api_token: []
summary: Delete batch group.
tags:
- Batch
x-soracom-cli:
- batch-groups delete
get:
description: |
Returns details of the specified batch group.
operationId: getBatchGroup
parameters:
- description: Batch group ID.
in: path
name: batch_group_id
required: true
schema:
type: string
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/BatchGroupResponse'
description: The batch group was found.
"404":
description: Batch group not found.
security:
- api_key: []
api_token: []
summary: Get batch group.
tags:
- Batch
x-soracom-cli:
- batch-groups get
put:
description: |
Updates the name or description of the specified batch group.
operationId: updateBatchGroup
parameters:
- description: Batch group ID.
in: path
name: batch_group_id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateBatchGroupRequest'
required: true
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/BatchGroupResponse'
description: The batch group was updated.
"404":
description: Batch group not found.
security:
- api_key: []
api_token: []
summary: Update batch group.
tags:
- Batch
x-soracom-cli:
- batch-groups update
/batch_groups/{batch_group_id}/jobs:
get:
description: Returns a list of batch jobs in the specified batch group.
operationId: listBatchJobs
parameters:
- description: Batch group ID.
in: path
name: batch_group_id
required: true
schema:
type: string
- description: Maximum number of batch jobs to retrieve. The number of batch
jobs returned may be less than the specified value.
example: 10
in: query
name: limit
required: false
schema:
format: int32
type: integer
- description: The value of the `x-soracom-next-key` header returned in the
response to the last request. Specify this to retrieve the next page of
batch jobs.
in: query
name: last_evaluated_key
required: false
schema:
type: string
responses:
"200":
content:
application/json:
schema:
items:
$ref: '#/components/schemas/BatchJobResponse'
type: array
description: A list of batch jobs was retrieved successfully.
"404":
description: Batch group not found.
security:
- api_key: []
api_token: []
summary: List batch jobs.
tags:
- Batch
x-soracom-cli:
- batch-groups jobs list
x-soracom-cli-pagination:
request:
param: last_evaluated_key
response:
header: x-soracom-next-key
post:
description: |
Create a new batch job and run it. A batch job consists of multiple tasks, each representing an API operation to be performed. Tasks are executed using the permissions of the user that created the batch job API. Batch job information is retained for 32 days.
**System Limits:**
- Each batch job is limited to a single API action. Mixing different APIs in the same job is not supported.
- Each batch job is limited to a maximum of 10,000 tasks.
- Only one batch job per API action can be created and processed at a time.
- Batch jobs may be delayed or restricted if system load is high. If this occurs, please wait and try again later.
operationId: createBatchJob
parameters:
- description: Batch group ID.
in: path
name: batch_group_id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateBatchJobRequest'
required: true
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/BatchJobResponse'
description: The batch job has been created and execution has started.
"400":
description: |
Bad request. This error can occur in the following cases:
- Attempting to mix different APIs in a single batch job
- Already running a batch job with the same API for this operator
"404":
description: Batch group not found.
"429":
description: Batch job execution is restricted due to high system load.
security:
- api_key: []
api_token: []
summary: Create and run batch job.
tags:
- Batch
x-soracom-cli:
- batch-groups jobs create
/batch_groups/{batch_group_id}/jobs/{job_id}:
get:
description: |
Returns information about the specified batch job.
operationId: getBatchJob
parameters:
- description: Batch group ID.
in: path
name: batch_group_id
required: true
schema:
type: string
- description: Batch job ID.
in: path
name: job_id
required: true
schema:
type: string
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/BatchJobResponse'
description: The batch job was found.
"404":
description: Batch job not found.
security:
- api_key: []
api_token: []
summary: Get batch job.
tags:
- Batch
x-soracom-cli:
- batch-groups jobs get
/batch_groups/{batch_group_id}/jobs/{job_id}/tasks:
get:
description: |
Returns a list of tasks in the specified batch job. Each task represents an individual API operation executed as part of the batch job.
operationId: listTasksOfBatchJob
parameters:
- description: Batch group ID.
in: path
name: batch_group_id
required: true
schema:
type: string
- description: Batch job ID.
in: path
name: job_id
required: true
schema:
type: string
- description: Maximum number of tasks to retrieve. The number of tasks returned
may be less than the specified value.
example: 10
in: query
name: limit
required: false
schema:
format: int32
type: integer
- description: Filter by task status.
in: query
name: status
required: false
schema:
enum:
- pending
- success
- error
type: string
- description: The value of the `x-soracom-next-key` header returned in the
response to the last request. Specify this to retrieve the next page of
tasks.
in: query
name: last_evaluated_key
required: false
schema:
type: string
responses:
"200":
content:
application/json:
schema:
items:
$ref: '#/components/schemas/BatchTaskResponse'
type: array
description: A list of batch tasks was retrieved successfully.
"404":
description: Batch job not found.
security:
- api_key: []
api_token: []
summary: List tasks.
tags:
- Batch
x-soracom-cli:
- batch-groups jobs list-tasks
x-soracom-cli-pagination:
request:
param: last_evaluated_key
response:
header: x-soracom-next-key
/bills:
get:
description: |
Gets a list of finalized past billing history.
**Warning**: The maximum information you can get is for the last 18 months. If you need the information before that time, please contact [Soracom Support](https://support.soracom.io).
operationId: getBillingHistory
responses:
"200":
content:
application/json:
example:
billList:
- amount: 28734
paymentStatus: paid
paymentTransactionId: 12345678901234567_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
state: closed
yearMonth: "202208"
- amount: 27075
paymentStatus: paid
paymentTransactionId: 12345678901234567_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
state: closed
yearMonth: "202207"
schema:
$ref: '#/components/schemas/GetBillingHistoryResponse'
description: A list of finalized past billing history.
security:
- api_key: []
api_token: []
summary: Gets a list of finalized past billing history
tags:
- Billing
x-soracom-cli:
- bills list
/bills/{yyyyMM}:
get:
description: |
Gets a finalized past billing history for the specified month. If you specify current month (the month in which the usage fee has not yet been finalized), you will get the preliminary value.
**Warning**: The maximum information you can get is for the last 18 months. If you need the information before that time, please contact [Soracom Support](https://support.soracom.io).
operationId: getBilling
parameters:
- description: Target year and month
in: path
name: yyyyMM
required: true
schema:
type: string
responses:
"200":
content:
application/json:
example:
amount: 28734
currency: JPY
paymentStatus: paid
paymentTransactionId: 12345678901234567_xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
state: closed
yearMonth: "202208"
schema:
$ref: '#/components/schemas/MonthlyBill'
description: The billing history for the specified month.
"404":
description: |
- The billing history for the specified month has not been finalized.
- There is no charge for the specified month.
security:
- api_key: []
api_token: []
summary: Gets a finalized past billing history for the specified month
tags:
- Billing
x-soracom-cli:
- bills get
/bills/{yyyyMM}/daily:
get:
description: |
Gets a daily bill for the specified month. Fees charged on a monthly basis cannot be retrieved. If you specify current month (a month for which the fee has not yet been finalized), a preliminary value will be returned.
**Warning**: The maximum information you can get is for the last 18 months. If you need the information before that time, please contact [Soracom Support](https://support.soracom.io).
operationId: getBillingPerDay
parameters:
- description: Target year and month
in: path
name: yyyyMM
required: true
schema:
type: string
responses:
"200":
content:
application/json:
example:
billList:
- amount: 285
currency: JPY
date: "20220902"
- amount: 580
currency: JPY
date: "20220901"
schema:
$ref: '#/components/schemas/DailyBillResponse'
description: Daily billing information for the specified month.
"404":
description: Bill not found.
security:
- api_key: []
api_token: []
summary: Get a daily bill
tags:
- Billing
x-soracom-cli:
- bills get-daily
/bills/{yyyyMM}/export:
post:
description: |
Export historical [Detailed billing CSV](/en/docs/account/billing/#detailed-billing-csv) to dedicated storage and issue URL to download.
**Warning**: The maximum information you can get is for the last 18 months. If you need the information before that time, please contact [Soracom Support](https://support.soracom.io).
operationId: exportBilling
parameters:
- description: Target year and month
in: path
name: yyyyMM
required: true
schema:
type: string
- description: |
Specify how to get the URL to download the billing details CSV.
- `async`: Get the `exportedFieldId` without waiting for the URL to be issued on the Soracom platform. Specify this `exportedFieldId` in [Files:getExportedFile API](#!/Files/getExportedFile) to get the URL. If the file size of the billing details CSV is huge, use `async`.
- `sync` (default): Wait for the URL to be issued on the Soracom platform. However, if the file size of the billing details CSV is huge, it may time out and the URL cannot be retrieved. If the timeout occurs, specify `async
# --- truncated at 32 KB (929 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/soracom/refs/heads/main/openapi/soracom-platform-api-openapi.yml