Terminal Issues API
The Issues API from Terminal — 2 operation(s) for issues.
The Issues API from Terminal — 2 operation(s) for issues.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/terminal-telematics:terminal-telematics-issues-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. By signing up you are subscribing to the APIs.io and API Evangelist newsletters — you can unsubscribe from any issue. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Terminal Telematics Issues API
description: Terminal is a unified API that makes it easy to integrate with the leading telematics service providers.
version: '0.0'
contact:
name: Terminal
email: connect@withterminal.com
url: https://www.withterminal.com
servers:
- url: https://api.withterminal.com/tsp/v1
description: Production
- url: https://api.sandbox.withterminal.com/tsp/v1
description: Sandbox
security:
- Authorization: []
tags:
- name: Issues
paths:
/issues:
x-mcp:
enabled: true
get:
x-mcp: all
summary: List Issues
tags:
- Issues
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/Issue'
next:
$ref: '#/components/schemas/PaginationCursor'
required:
- results
'400':
$ref: '#/components/responses/BadRequestError'
'401':
$ref: '#/components/responses/UnauthorizedError'
'403':
$ref: '#/components/responses/ForbiddenError'
'429':
$ref: '#/components/responses/TooManyRequestsError'
'500':
$ref: '#/components/responses/InternalServerError'
'504':
$ref: '#/components/responses/GatewayTimeoutError'
operationId: listIssues
x-operation-category: control-plane
parameters:
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/Cursor'
- schema:
$ref: '#/components/schemas/ISODateTime'
in: query
name: lastReportedAfter
description: Timestamp to start when the issue was last observed
- schema:
$ref: '#/components/schemas/ISODateTime'
in: query
name: lastReportedBefore
description: Timestamp to end when the issue was last observed
- schema:
type: string
enum:
- connection
in: query
name: expand
description: Expand related resources to see all details
- schema:
$ref: '#/components/schemas/ConnectionId'
in: query
name: connectionId
description: Filter issues to a specific connection
- schema:
$ref: '#/components/schemas/IssueCode'
in: query
name: errorCode
description: Filter issues to a specific semantic Issue code
- schema:
type: string
enum:
- ongoing
- resolved
in: query
name: status
description: Filter issues to a specific status
description: 'List all issues that have been observed by Terminal.
Issues are generated when we observe something that may impact the completeness or accuracy of the data we provide but do not justify a full error.
For example, if we lack permissions for a specific resource or need to skip an item due to invalid data.'
/issues/{issueId}/resolve:
parameters:
- schema:
$ref: '#/components/schemas/IssueId'
name: issueId
in: path
required: true
x-mcp:
enabled: true
post:
summary: Resolve Issue
description: Mark an issue's status as `resolved` until the issue is observed again.
tags:
- Issues
operationId: resolveIssue
x-operation-category: control-plane
responses:
'200':
description: OK
content:
application/json:
schema:
$ref: '#/components/schemas/Issue'
'400':
$ref: '#/components/responses/BadRequestError'
'401':
$ref: '#/components/responses/UnauthorizedError'
'403':
$ref: '#/components/responses/ForbiddenError'
'422':
$ref: '#/components/responses/UnprocessableEntityError'
'429':
$ref: '#/components/responses/TooManyRequestsError'
'500':
$ref: '#/components/responses/InternalServerError'
'504':
$ref: '#/components/responses/GatewayTimeoutError'
parameters: []
components:
schemas:
FullConnection:
title: Full Connection
description: The connection your application has with your customer's TSP.
allOf:
- title: Connection Base
type: object
description: Fields shared by all connection records.
properties:
id:
$ref: '#/components/schemas/ConnectionId'
company:
type: object
properties:
name:
type: string
example: Frank's Trucking
description: Optional name of the connection.
dotNumbers:
type: array
description: Optional DOT numbers associated with this connection.
items:
type: string
example: '1234567'
account:
type: object
properties:
name:
type: string
example: Frank's Trucking
description: The name of the account according to the provider.
dotNumbers:
type: array
description: DOT numbers associated with the account according to the provider.
items:
type: string
example: '1234567'
user:
type: object
description: The user of the provider account that created the connection.
properties:
sourceId:
description: The ID of the user in the provider's system.
example: '1234567'
type: string
firstName:
example: John
type: string
lastName:
example: Doe
type: string
email:
example: john.doe@example.com
type: string
provider:
type: object
required:
- code
- name
properties:
code:
$ref: '#/components/schemas/ProviderCode'
name:
type: string
example: Geotab
description: The name of the Telematics Service Provider.
externalId:
type: string
example: '1234'
description: An optional ID from your system that can be used to reference connections.
sourceId:
$ref: '#/components/schemas/SourceId'
description: 'The ID used in the source system to represent the account this connection has or had access to.
This may be an `organizationId` or `accountId`.
Note: not all systems expose this information, in which case it may be undefined.'
syncMode:
$ref: '#/components/schemas/SyncMode'
token:
type: string
example: con_tkn_22vUhkC6tgre4kwaYfUkCDA1rzn6eyb4
pattern: ^con_tkn_\S+$
description: This token is used when interacting with a connections' data.
tags:
type: array
description: An optional list of tags from your system that can be used to reference connections.
items:
type: string
example: Tag Name
createdAt:
$ref: '#/components/schemas/ISODateTime'
updatedAt:
$ref: '#/components/schemas/ISODateTime'
required:
- id
- company
- account
- provider
- syncMode
- token
- createdAt
- updatedAt
- type: object
properties:
status:
type: string
enum:
- connected
- disconnected
- archived
- pending_deletion
description: The current status of the connection.
options:
$ref: '#/components/schemas/ProviderOptions'
filters:
$ref: '#/components/schemas/ConnectionFilters'
linkUrl:
type: string
format: uri
example: https://link.withterminal.com/connection/{CONNECTION_ID}?key={PUBLISHABLE_KEY}
description: The URL to send your user to in order to have them re-authenticate the connection.
required:
- status
- options
- linkUrl
SourceId:
title: SourceId
type: string
example: '123456789'
description: The ID used to represent the entity in the source system.
IssueResolutionType:
title: IssueResolutionType
type: string
description: How an issue is expected to be investigated or resolved.
example: action_required
enum:
- action_required
- automatic_retry
- terminal_managed
- known_limitation
- investigation_required
IssueCode:
title: IssueCode
type: string
description: Stable semantic identifier for an Issue and its remediation workflow. Legacy values remain in the schema for source compatibility but are not emitted after migration.
example: permission_missing
enum:
- missing_permissions
- exceeded_retention_window
- invalid_source_id
- unknown_device_type
- missing_safety_configuration
- inaccessible_data
- manually_disabled
- permission_missing
- oauth_scope_missing
- subscription_required
- retention_window_exceeded
- provider_data_inaccessible
- invalid_source_identifier
- unsupported_device_type
- stream_disabled
- provider_provisioning_pending
- provider_feature_not_enabled
- missing_vehicle_identifier
- missing_vehicle_assignment
- provider_capability_not_supported
- provider_source_data_invalid
- provider_partially_configured
- managed_poll_returned_no_data
- managed_poll_failed
- data_delayed
PaginationCursor:
title: Pagination Cursor
type: string
example: cD0yMDIxLTAxLTA2KzAzJTNBMjQlM0E1My40MzQzMjYlMkIwMCUzQTAw
description: Cursor used for pagination.
format: cursor
pattern: ^[A-Za-z0-9+/=_-]+$
Issue:
title: Issue
type: object
x-model-category: platform
properties:
id:
$ref: '#/components/schemas/IssueId'
resolutionType:
$ref: '#/components/schemas/IssueResolutionType'
documentationUrl:
type: string
format: uri
description: Direct link to the resolution guide for this semantic issue.
example: https://docs.withterminal.com/issues/permission-missing
connection:
$ref: '#/components/schemas/ExpandableConnection'
description: The connection this issue belongs to.
status:
type: string
enum:
- ongoing
- resolved
example: ongoing
error:
type: object
properties:
code:
$ref: '#/components/schemas/IssueCode'
message:
type: string
example: Failed to ingest HOS Logs, missing permissions to access Duty Status Logs
required:
- code
- message
firstReportedAt:
$ref: '#/components/schemas/ISODateTime'
lastReportedAt:
$ref: '#/components/schemas/ISODateTime'
required:
- id
- connection
- status
- error
- firstReportedAt
- lastReportedAt
x-description: An issue is a problem we encountered while ingesting data from a connection that may impact the quality or completeness of the data.
ExpandedConnection:
title: Expanded Connection
oneOf:
- $ref: '#/components/schemas/FullConnection'
- $ref: '#/components/schemas/DeletedConnection'
x-description: The connection your application has with your customer's TSP.
ErrorPathDetail:
title: ErrorPathDetail
type: object
properties:
message:
type: string
example: '''vehicleId'' property must be a valid ulid'
path:
type: string
example: '{requestQuery}.vehicleId'
suggestion:
type: string
example: Please ensure you submit a valid 'vehicleId' property
context:
type: object
required:
- message
- path
ProviderOptions:
type: object
oneOf:
- type: object
properties:
ingestHistoryFromSourceSystem:
default: true
description: By default our system will ingest Vehicle Locations and Stat Logs from the source system. Omnitracs also supports history at a higher sample rate through a historical file process. If you are using these historical files and want to avoid mixing the data sources, set this to false.
type: boolean
required: []
title: Omnitracs Options
- type: object
properties:
ingestHistoryFromSourceSystem:
default: true
description: By default our system will ingest Vehicle Locations and Stat Logs from the source system. Omnitracs also supports history at a higher sample rate through a historical file process. If you are using these historical files and want to avoid mixing the data sources, set this to false.
type: boolean
required: []
title: Omnitracs ES Options
- type: object
properties:
ingestHistoryFromSourceSystem:
default: true
description: By default our system will ingest Vehicle Locations and Stat Logs from the source system. Omnitracs also supports history at a higher sample rate through a historical file process. If you are using these historical files and want to avoid mixing the data sources, set this to false.
type: boolean
required: []
title: Omnitracs XRS Options
DeletedConnection:
title: Deleted Connection
description: A retained connection record after connection-scoped data has been deleted.
allOf:
- $ref: '#/components/schemas/FullConnection/allOf/0'
- type: object
properties:
status:
type: string
enum:
- deleting
- deleted
deletedAt:
$ref: '#/components/schemas/ISODateTime'
description: When Terminal finished deleting connection-scoped data. Present once status is `deleted`.
required:
- status
ConnectionFilters:
type: object
properties:
vehicles:
type: object
properties:
status:
type: string
enum:
- active
- inactive
description: Filter connection to only include data related to vehicles with a specified status
excludeIds:
type: array
items:
$ref: '#/components/schemas/VehicleId'
description: IDs of vehicles to exclude from data ingestion
includeIds:
type: array
items:
$ref: '#/components/schemas/VehicleId'
description: IDs of vehicles to include in data ingestion (takes priority over other filters)
drivers:
type: object
properties:
status:
type: string
enum:
- active
- inactive
description: Filter connection to only include data related to drivers with a specified status
excludeIds:
type: array
items:
$ref: '#/components/schemas/DriverId'
description: IDs of drivers to exclude from data ingestion
includeIds:
type: array
items:
$ref: '#/components/schemas/DriverId'
description: IDs of drivers to include in data ingestion (takes priority over other filters)
description: 'Filters applied to connection data. Across all lists, the maximum is about 8,000 IDs. A larger update is rejected with 422 and is not saved. If one list contains most vehicles or drivers, use the opposite list: excludeIds for the ones to skip, or includeIds for the ones to keep.'
DriverId:
title: DriverId
description: Unique identifier for the driver in Terminal.
type: string
format: ulid
pattern: ^drv_[0-9A-HJKMNP-TV-Z]{26}$
example: drv_01D8ZQFGHVJ858NBF2Q7DV9MNC
SyncMode:
title: SyncMode
type: string
enum:
- automatic
- manual
description: 'Enum values:
- `automatic`: Terminal will keep this connections data up to date
- `manual`: Terminal will only sync data upon request'
default: automatic
IssueId:
title: IssueId
type: string
format: ulid
pattern: ^isu_[0-9A-HJKMNP-TV-Z]{26}$
example: isu_01D8ZQFGHVJ858NBF2Q7DV9MNC
ConnectionId:
title: ConnectionId
type: string
format: ulid
example: conn_01GV12VR4DJP70GD1ZBK0SDWFH
ProviderCode:
type: string
example: geotab
description: Every provider has a unique code to identify it across Terminal's system. You can find each provider's code under [provider details](/providers).
ISODateTime:
title: ISODateTime
type: string
format: date-time
example: '2021-01-06T03:24:53.000Z'
description: '[ISO 8601](https://www.w3.org/TR/NOTE-datetime) date'
VehicleId:
title: VehicleId
description: Unique identifier for the vehicle in Terminal.
type: string
format: ulid
pattern: ^vcl_[0-9A-HJKMNP-TV-Z]{26}$
example: vcl_01D8ZQFGHVJ858NBF2Q7DV9MNC
ExpandableConnection:
title: ExpandableConnection
example: conn_01GV12VR4DJP70GD1ZBK0SDWFH
oneOf:
- $ref: '#/components/schemas/ConnectionId'
- $ref: '#/components/schemas/ExpandedConnection'
responses:
ForbiddenError:
description: Forbidden
content:
application/json:
schema:
type: object
properties:
code:
enum:
- forbidden
message:
type: string
example: Forbidden Request
detail:
type: string
example: Please ensure the connection token matches the resource you are attempting to access.
required:
- code
- message
BadRequestError:
description: Bad Request
content:
application/json:
schema:
type: object
properties:
code:
enum:
- bad_request
message:
type: string
example: Invalid request body
detail:
type: array
items:
$ref: '#/components/schemas/ErrorPathDetail'
required:
- code
- message
GatewayTimeoutError:
description: Gateway Timeout Error
content:
application/json:
schema:
type: object
properties:
code:
enum:
- gateway_timeout
- provider_timeout
description: '`provider_timeout` means the telematics provider did not respond in time, or responded too slowly to finish the request (for example, while paginating). Retry later or narrow the request, for example with a shorter time range or smaller `limit`. `gateway_timeout` means Terminal could not finish the request in time for another reason.'
message:
type: string
example: Gateway Timeout
required:
- code
- message
UnauthorizedError:
description: Unauthorized
content:
application/json:
schema:
type: object
properties:
code:
enum:
- unauthorized
message:
type: string
example: Unauthorized Request
detail:
type: string
example: Please ensure you have a valid API key
required:
- code
- message
InternalServerError:
description: Internal Server Error
content:
application/json:
schema:
type: object
properties:
code:
enum:
- internal_server_error
message:
type: string
example: Internal Server Error
detail:
type: string
example: Something went wrong
required:
- code
- message
UnprocessableEntityError:
description: Unprocessable Entity
content:
application/json:
schema:
type: object
properties:
code:
enum:
- unprocessable_entity
- connection_disconnected
- insufficient_permissions
- invalid_credentials
- oauth_client_id_unknown
example: connection_disconnected
message:
type: string
example: Connection must be connected to perform this action
detail:
type: array
items:
$ref: '#/components/schemas/ErrorPathDetail'
example: []
required:
- code
- message
TooManyRequestsError:
description: Too Many Requests
content:
application/json:
schema:
type: object
additionalProperties: true
properties:
code:
enum:
- too_many_requests
retryAfter:
description: The number of seconds to wait before retrying the request
type: integer
example: 60
message:
type: string
example: Too Many Requests
detail:
type: string
example: You have exceeded your rate limit. Please try again later.
required:
- code
- message
parameters:
Limit:
name: limit
in: query
required: false
schema:
type: integer
description: The maximum number of results to return in a page.
Cursor:
name: cursor
in: query
schema:
type: string
format: cursor
pattern: ^[A-Za-z0-9+/=_-]+$
example: cD0yMDIxLTAxLTA2KzAzJTNBMjQlM0E1My40MzQzMjYlMkIwMCUzQTAw
description: Pagination cursor to start requests from
securitySchemes:
Authorization:
type: http
scheme: bearer