openapi: 3.0.0 info: title: Soracom Harvest API description: Soracom Harvest data and file ingest, storage, retrieval, and export for time-series and binary device payloads. 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: /data/{resource_type}/{resource_id}: get: description: 'Returns a list of data entries sent to Harvest Data from a device that match certain criteria. If the total number of entries does not fit in one page, a URL for accessing the next page is returned in the `link` header of the response. ' operationId: getDataEntries parameters: - description: Type of data source resource. in: path name: resource_type required: true schema: enum: - Subscriber - LoraDevice - Sim - SigfoxDevice - Device - SoraCam type: string - description: 'ID of data source resource. The ID to be specified depends on the value of `resource_type`. | `resource_type` | The ID you specify | |-|-| | `Subscriber` | IMSI of the IoT SIM | | `LoraDevice` | ID of the LoRaWAN device | | `Sim` | SIM ID of the IoT SIM | | `SigfoxDevice` | ID of the Sigfox device | | `Device` | ID of the Inventory device | | `SoraCam` | Device ID of the compatible camera device | ' in: path name: resource_id required: true schema: type: string - description: Start time for the data entries search range (UNIX time in milliseconds). in: query name: from required: false schema: type: integer - description: End time for the data entries search range (UNIX time in milliseconds). in: query name: to required: false schema: type: integer - description: Sort order of the data entries. Either descending (latest data entry first) or ascending (oldest data entry first). in: query name: sort required: false schema: default: desc enum: - desc - asc type: string - description: Maximum number of data entries to retrieve (value range is 1 to 1000). The default is `10`. in: query name: limit required: false schema: maximum: 1000 minimum: 1 type: integer - description: The value of the `x-soracom-next-key` header from the previous response. Specify this to retrieve the next page. in: query name: last_evaluated_key required: false schema: type: string responses: '200': content: application/json: schema: items: $ref: '#/components/schemas/DataEntry' type: array description: A list of data entries sent to Harvest Data from the specified resource. security: - api_key: [] api_token: [] summary: Get data sent to Harvest Data from a resource. tags: - DataEntry x-soracom-cli: - data get-entries x-soracom-cli-pagination: request: param: last_evaluated_key response: header: x-soracom-next-key /data/{resource_type}/{resource_id}/{time}: delete: description: Deletes a data entry identified with resource ID and timestamp operationId: deleteDataEntry parameters: - description: Type of data source resource. in: path name: resource_type required: true schema: enum: - Subscriber - LoraDevice - Sim - SigfoxDevice - Device - SoraCam type: string - description: 'ID of data source resource. The ID to be specified depends on the value of `resource_type`. | `resource_type` | The ID you specify | |-|-| | `Subscriber` | IMSI of the IoT SIM | | `LoraDevice` | ID of the LoRaWAN device | | `Sim` | SIM ID of the IoT SIM | | `SigfoxDevice` | ID of the Sigfox device | | `Device` | ID of the Inventory device | | `SoraCam` | Device ID of the compatible camera device | ' in: path name: resource_id required: true schema: type: string - description: Timestamp of the target data entry to delete (UNIX time in milliseconds). in: path name: time required: true schema: type: integer responses: '204': description: The data entry has been successfully deleted security: - api_key: [] api_token: [] summary: Deletes a data entry tags: - DataEntry x-soracom-cli: - data delete-entry get: description: Gets a data entry identified with resource ID and timestamp operationId: getDataEntry parameters: - description: Type of data source resource. in: path name: resource_type required: true schema: enum: - Subscriber - LoraDevice - Sim - SigfoxDevice - Device - SoraCam type: string - description: 'ID of data source resource. The ID to be specified depends on the value of `resource_type`. | `resource_type` | The ID you specify | |-|-| | `Subscriber` | IMSI of the IoT SIM | | `LoraDevice` | ID of the LoRaWAN device | | `Sim` | SIM ID of the IoT SIM | | `SigfoxDevice` | ID of the Sigfox device | | `Device` | ID of the Inventory device | | `SoraCam` | Device ID of the compatible camera device | ' in: path name: resource_id required: true schema: type: string - description: Timestamp of the target data entry to get (UNIX time in milliseconds). in: path name: time required: true schema: type: integer responses: '200': content: application/json: schema: $ref: '#/components/schemas/DataEntry' description: The data entry specified with resource ID and timestamp '404': description: No such entry found security: - api_key: [] api_token: [] summary: Gets a data entry tags: - DataEntry x-soracom-cli: - data get-entry /data/categories/{category}: get: description: 'Returns a list of data entries that belong to a specific category. If the total number of entries does not fit in one page, a URL for accessing the next page is returned in the `link` header of the response. ' operationId: getDataEntriesByCategory parameters: - description: Name of the category to filter data entries. in: path name: category required: true schema: type: string - description: Start time for the data entries search range (UNIX time in milliseconds). in: query name: from required: false schema: type: integer - description: End time for the data entries search range (UNIX time in milliseconds). in: query name: to required: false schema: type: integer - description: Sort order of the data entries. Either descending (latest data entry first) or ascending (oldest data entry first). in: query name: sort required: false schema: default: desc enum: - desc - asc type: string - description: Maximum number of data entries to retrieve (value range is 1 to 1000). The default is `10`. in: query name: limit required: false schema: maximum: 1000 minimum: 1 type: integer - description: The value of the `x-soracom-next-key` header from the previous response. Specify this to retrieve the next page. in: query name: last_evaluated_key required: false schema: type: string responses: '200': content: application/json: schema: items: $ref: '#/components/schemas/DataEntry' type: array description: A list of data entries belonging to the specified category. security: - api_key: [] api_token: [] summary: Get data entries for a specific category tags: - DataEntry x-soracom-cli: - data get-entries-by-category x-soracom-cli-pagination: request: param: last_evaluated_key response: header: x-soracom-next-key /data/metadata/resources: get: description: 'Returns a list of data source resources that have sent data. If the total number of data source resources does not fit in one page, a URL for accessing the next page is returned in the `link` header of the response. ' operationId: listDataResourceMetadata parameters: - description: 'Type of data source resource. - `Subscriber`: IoT SIM. - `LoraDevice`: LoRaWAN device. - `Sim`: IoT SIM. - `SigfoxDevice`: Sigfox device. - `Device`: Inventory device. - `SoraCam`: Compatible camera device. ' in: query name: resource_type required: false schema: enum: - Subscriber - LoraDevice - Sim - SigfoxDevice - Device - SoraCam type: string - description: Maximum number of data entries to retrieve. in: query name: limit required: false schema: type: integer - description: The value of the `x-soracom-next-key` header from the previous response. Specify this to retrieve the next page. in: query name: last_evaluated_key required: false schema: type: string responses: '200': content: application/json: schema: items: $ref: '#/components/schemas/DataResourceMetadata' type: array description: A list of data source resources that have sent data to Harvest Data. security: - api_key: [] api_token: [] summary: Get the list of data source resources tags: - DataEntry x-soracom-cli: - data list-resource-metadata x-soracom-cli-pagination: request: param: last_evaluated_key response: header: x-soracom-next-key /data/resources: get: deprecated: true description: 'Returns a list of data source resources that have sent data. If the total number of data source resources does not fit in one page, a URL for accessing the next page is returned in the `link` header of the response. ' operationId: listDataSourceResources parameters: - description: 'Type of data source resource. - `Subscriber`: IoT SIM. - `LoraDevice`: LoRaWAN device. - `Sim`: IoT SIM. - `SigfoxDevice`: Sigfox device. - `Device`: Inventory device. - `SoraCam`: Compatible camera device. ' in: query name: resource_type required: false schema: enum: - Subscriber - LoraDevice - Sim - SigfoxDevice - Device - SoraCam type: string - description: Maximum number of data entries to retrieve. in: query name: limit required: false schema: type: integer - description: The value of the `x-soracom-next-key` header from the previous response. Specify this to retrieve the next page. in: query name: last_evaluated_key required: false schema: type: string responses: '200': content: application/json: schema: items: $ref: '#/components/schemas/DataResourceMetadata' type: array description: A list of data source resources that have sent data to Harvest Data. security: - api_key: [] api_token: [] summary: Get the list of data source resources tags: - DataEntry x-soracom-cli: - data list-source-resources x-soracom-cli-pagination: request: param: last_evaluated_key response: header: x-soracom-next-key /files: get: description: Returns a list of file entries which beginnings of their file paths are matched with the `prefix` query string in the ascending sorted UTF-8 bytes order of their file paths. An empty list is returned if the prefix does not match with any paths of file entries. operationId: findFiles parameters: - description: Scope of the request. Specify `private` to handle files uploaded to Harvest Files. in: query name: scope required: true schema: enum: - private - public type: string - description: Prefix to match with file path. in: query name: prefix required: true schema: type: string - description: Maximum number of file entries to be returned. in: query name: limit required: false schema: default: 10 type: integer - description: The filePath of the last file entry retrieved on the previous page. By specifying this parameter, you can continue to retrieve the list from the next file entry onward. in: query name: last_evaluated_key required: false schema: type: string responses: '200': content: application/json: schema: items: $ref: '#/components/schemas/FileEntry' type: array description: List of file entries found with query parameters. Empty list if there is no file entry matching prefix. '404': description: The specified scope does not exist. security: - api_key: [] api_token: [] summary: Find files with prefix query parameter in the scope tags: - FileEntry x-soracom-cli: - files find x-soracom-cli-pagination: request: param: last_evaluated_key response: header: x-soracom-next-key /files/{scope}/{path}: delete: description: Deletes the file specified by scope and path. Only `private` scope is allowed for the operation. operationId: deleteFile parameters: - description: Scope of the request. Specify `private` to handle files uploaded to Harvest Files. in: path name: scope required: true schema: default: private enum: - private type: string - description: Target path. in: path name: path required: true schema: type: string responses: '204': description: The specified file is successfully deleted. '404': description: No such file. security: - api_key: [] api_token: [] summary: Deletes the file specified by scope and path. tags: - FileEntry x-soracom-cli: - files delete get: description: Download file specified by the path and the scope. Note that [FileEntry:listFiles API](#!/FileEntry/listFiles) will be called if the path ends with `/`. operationId: getFile parameters: - description: Scope of the request. Specify `private` to handle files uploaded to Harvest Files. in: path name: scope required: true schema: default: private enum: - private - public type: string - description: Target path. in: path name: path required: true schema: type: string responses: '302': description: Redirection to a link to download a file. If the specified path is a directory, redirection to the listFiles API. '404': description: No such file. security: - api_key: [] api_token: [] summary: Download file specified by the path and the scope tags: - FileEntry x-soracom-cli: - files get head: description: Gets the metadata of the file specified by the path and the scope. operationId: getFileMetadata parameters: - description: Scope of the request. Specify `private` to handle files uploaded to Harvest Files. in: path name: scope required: true schema: default: private enum: - private - public type: string - description: Target path. in: path name: path required: true schema: type: string responses: '200': description: Metadata of the file headers: Content-Length: description: File size (bytes) schema: type: integer Content-Type: description: File's Content-Type schema: type: string ETag: description: Identifier representing the file version schema: type: string '404': description: No such file. security: - api_key: [] api_token: [] summary: Gets the metadata of the file specified by the path and the scope tags: - FileEntry x-soracom-cli: - files get-metadata put: description: Uploads the file to the specified path in the scope. Only `private` scope is allowed for the operation. operationId: putFile parameters: - description: Scope of the request. Specify `private` to handle files uploaded to Harvest Files. in: path name: scope required: true schema: default: private enum: - private type: string - description: Target path. in: path name: path required: true schema: type: string - description: Content-Type of the file to be uploaded. in: header name: content-type schema: type: string requestBody: content: '*/*': schema: format: binary type: string description: Contents of the file to be updated. required: true responses: '200': description: File is successfully updated with the content. '201': description: File is successfully created. security: - api_key: [] api_token: [] summary: Uploads the file to the specified path in the scope. tags: - FileEntry x-soracom-cli: - files put /files/{scope}/{path}/: delete: description: Deletes the directory specified by scope and path. Only `private` scope is allowed for the operation. operationId: deleteDirectory parameters: - description: Scope of the request. Specify `private` to handle files uploaded to Harvest Files. in: path name: scope required: true schema: default: private enum: - private type: string - description: Target path. in: path name: path required: true schema: type: string responses: '204': description: The specified directory is successfully deleted. '400': description: The specified directory is not empty. '404': description: No such directory. security: - api_key: [] api_token: [] summary: Deletes the directory specified by scope and path tags: - FileEntry x-soracom-cli: - files delete-directory get: description: 'Returns files and directories from the directory specified by the scope and path. Note that [FileEntry:getFile API](#!/FileEntry/getFile) will be called if the path does not end in `/`. If the total number of entries does not fit in one page, a URL for accessing the next page is returned in the `link` header of the response. ' operationId: listFiles parameters: - description: Scope of the request. Specify `private` to handle files uploaded to Harvest Files. in: path name: scope required: true schema: default: private enum: - private - public type: string - description: Target path. in: path name: path required: true schema: default: / type: string - description: Maximum number of file entries to be returned. in: query name: limit required: false schema: default: 10 type: integer - description: The filename of the last file entry retrieved on the previous page. By specifying this parameter, you can continue to retrieve the list from the next file entry onward. in: query name: last_evaluated_key required: false schema: type: string responses: '200': content: application/json: schema: items: $ref: '#/components/schemas/FileEntry' type: array description: Files and directories from the directory specified by the scope and path. '404': description: No such directory. security: - api_key: [] api_token: [] summary: Returns files and directories from the directory specified by the scope and path. tags: - FileEntry x-soracom-cli: - files list x-soracom-cli-pagination: request: param: last_evaluated_key response: header: x-soracom-next-key /files/exported/{exported_file_id}: get: description: 'Get the progress of the process when the file is exported asynchronously. If the export is complete, you will get the URL to download the file. You can download the file from the URL. The following APIs are available to export files asynchronously. The `exported_file_id` is the file output ID (the value of `exportedFileId`) obtained from the following API. - [Billing:exportBilling API](#!/Billing/exportBilling) - [Billing:exportLatestBilling API](#!/Billing/exportLatestBilling) - [Payment:exportPaymentStatement API](#!/Payment/exportPaymentStatement) - [Stats:exportAirStats API](#!/Stats/exportAirStats) - [Stats:exportBeamStats API](#!/Stats/exportBeamStats) - [Stats:exportFunkStats API](#!/Stats/exportFunkStats) - [Stats:exportFunnelStats API](#!/Stats/exportFunnelStats) - [Subscriber:exportSubscribers API](#!/Subscriber/exportSubscribers) ' operationId: getExportedFile parameters: - description: File export ID. in: path name: exported_file_id required: true schema: type: string responses: '200': content: application/json: example: status: exported url: https://soracom-xxxxxxxx-.... schema: $ref: '#/components/schemas/GetExportedFileResponse' description: OK security: - api_key: [] api_token: [] summary: Get the progress of the process when the file is exported asynchronously. tags: - Files x-soracom-cli: - files get-exported tags: - description: '[Soracom Harvest Data](/en/docs/harvest/)' name: DataEntry - description: '[Soracom Harvest Files](/en/docs/harvest/)' name: FileEntry - description: 'Download files exported by the following APIs: - [Billing](#/Billing) - [Payment: exportPaymentStatement](#/Payment/exportPaymentStatement) - [Stats](#/Stats) - [Subscriber:exportSubscribers](#/Subscriber/exportSubscribers) ' name: Files components: schemas: DataEntry: properties: category: type: string content: type: string contentType: type: string resourceId: type: string resourceType: enum: - Subscriber - LoraDevice - Sim - SigfoxDevice - Device - SoraCam type: string time: format: int64 type: integer type: object DataResourceMetadata: properties: attributeNames: items: type: string type: array lastModifiedTime: format: int64 type: integer resourceId: type: string resourceType: type: string type: object FileEntry: properties: contentLength: description: Content length of the file. format: int64 type: integer contentType: description: Content type of the file. type: string createdTime: description: Created time of the file. format: int64 type: integer directory: description: Parent directory name. type: string etag: description: ETag of the file. type: string filePath: description: Absolute path of the file. type: string filename: description: File name. type: string isDirectory: description: Whether the entry is directory or not. type: boolean lastModifiedTime: description: Last modified time of the file. format: int64 type: integer type: object GetExportedFileResponse: properties: status: description: 'Export status. - `processing`: Export is in progress. Please wait. - `exported`: Export has completed. The file is ready for download. - `failed`: Export has failed. ' enum: - processing - exported - failed type: string url: description: 'File download URL. Verify that the `status` is `exported`, then download the CSV file from the URL obtained from `url`. ```bash $ wget -O export.csv "https://soracom-xxxxxxxx-...." ``` ' type: string type: object securitySchemes: api_key: description: 'API key for authentication. Obtain this from the Soracom User Console or via the Auth API. Required in combination with an API token for all authenticated requests. ' in: header name: X-Soracom-API-Key type: apiKey api_token: description: 'API token for authentication. This token has an expiration time and must be refreshed periodically. Required in combination with an API key for all authenticated requests.' in: header name: X-Soracom-Token type: apiKey