Terminal Fault Codes API
The Fault Codes API from Terminal — 1 operation(s) for fault codes.
The Fault Codes API from Terminal — 1 operation(s) for fault codes.
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-fault-codes-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 Fault Codes 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: Fault Codes
paths:
/fault-codes/events:
parameters: []
x-mcp:
enabled: true
get:
x-mcp: all
summary: List Fault Code Events
responses:
'200':
description: OK
content:
application/json:
schema:
type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/FaultCodeEvent'
next:
$ref: '#/components/schemas/PaginationCursor'
required:
- results
'400':
$ref: '#/components/responses/BadRequestError'
'401':
$ref: '#/components/responses/UnauthorizedError'
'403':
$ref: '#/components/responses/ForbiddenError'
'410':
$ref: '#/components/responses/GoneError'
'429':
$ref: '#/components/responses/TooManyRequestsError'
'500':
$ref: '#/components/responses/InternalServerError'
'504':
$ref: '#/components/responses/GatewayTimeoutError'
operationId: listFaultCodeEvents
x-operation-category: core-data
x-required-permissions:
- fault-codes:read
parameters:
- $ref: '#/components/parameters/ConnectionToken'
- $ref: '#/components/parameters/Cursor'
- $ref: '#/components/parameters/Limit'
- $ref: '#/components/parameters/ModifiedAfter'
- $ref: '#/components/parameters/ModifiedBefore'
- schema:
$ref: '#/components/schemas/ISODateTime'
in: query
name: startAt
description: Only include fault code events after a provided date.
- schema:
$ref: '#/components/schemas/ISODateTime'
in: query
name: endAt
description: Only include fault code events before a provided date.
- $ref: '#/components/parameters/VehicleIds'
- schema:
type: string
enum:
- vehicle
in: query
name: expand
description: Expand resources in the returned response
- $ref: '#/components/parameters/Raw'
tags:
- Fault Codes
description: List all fault code events detected by the provider.
components:
schemas:
SourceId:
title: SourceId
type: string
example: '123456789'
description: The ID used to represent the entity in the source system.
ModifiedAt:
title: ModifiedAt
type: string
format: date-time
description: 'The date and time the record was last updated in Terminal. Note: this is not the date and time the record was updated in the provider''s system.'
DeletedAt:
title: DeletedAt
type: string
format: date-time
description: 'The date and time the record was deleted from Terminal. Note: this is not the date and time the record was deleted in the provider''s system.'
FaultCodeProtocol:
type: string
enum:
- j1939
- obdii
description: The diagnostic protocol used
RawDataList:
title: RawDataList
type: array
example: []
items:
$ref: '#/components/schemas/RawData'
SourceCreatedAt:
title: SourceCreatedAt
type: string
format: date-time
description: 'The date and time the record was created in the provider''s system. This timestamp comes directly from the source system and represents when the data was originally created there. Note: not all providers expose this.'
PaginationCursor:
title: Pagination Cursor
type: string
example: cD0yMDIxLTAxLTA2KzAzJTNBMjQlM0E1My40MzQzMjYlMkIwMCUzQTAw
description: Cursor used for pagination.
format: cursor
pattern: ^[A-Za-z0-9+/=_-]+$
DeviceId:
title: DeviceId
type: string
format: ulid
example: dvc_61D9ZWFGHVJ858NBF2Q7DV9MNC
AddedAt:
title: AddedAt
type: string
format: date-time
description: 'The date and time the record was ingested into Terminal. Note: this is not the date and time the record was created in the provider''s system.'
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
RawData:
title: RawData
type: object
properties:
provider:
type: string
schema:
type: string
extractedAt:
type: string
data:
type: object
required:
- provider
- schema
- extractedAt
- data
GroupId:
title: GroupId
type: string
format: ulid
example: group_01D8ZQFGHVJ858NBF2Q7DV9MNC
State:
title: State
type: string
enum:
- AL
- AK
- AS
- AZ
- AR
- CA
- CO
- CT
- DE
- FL
- GA
- GU
- HI
- ID
- IL
- IN
- IA
- KS
- KY
- LA
- ME
- MD
- MA
- MI
- MN
- MP
- MS
- MO
- MT
- NE
- NV
- NH
- NJ
- NM
- NY
- NC
- ND
- OH
- OK
- OR
- PA
- PR
- RI
- SC
- SD
- TN
- TX
- UT
- VT
- VA
- WA
- WV
- WI
- WY
- VI
- AB
- BC
- MB
- NB
- NL
- NS
- 'ON'
- PE
- QC
- SK
- NT
- NU
- UM
- YT
- DC
example: TN
description: US State or Canadian Province
SourceUpdatedAt:
title: SourceUpdatedAt
type: string
format: date-time
description: 'The date and time the record was updated in the provider''s system. This timestamp comes directly from the source system and represents when the data was last updated there. Note: not all providers expose this.'
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'
ExpandedVehicle:
title: Expanded Vehicle
type: object
additionalProperties: false
properties:
id:
$ref: '#/components/schemas/VehicleId'
sourceId:
$ref: '#/components/schemas/SourceId'
provider:
$ref: '#/components/schemas/ProviderCode'
status:
type: string
enum:
- active
- inactive
example: active
description: The status in the providers system
vin:
title: VIN
type: string
example: 1HGCM82633A004352
name:
type: string
example: Big Red
make:
type: string
example: Peterbilt
model:
type: string
example: Model 579
year:
type: integer
example: 2016
groups:
type: array
description: The groups the vehicle belongs to.
items:
$ref: '#/components/schemas/GroupId'
devices:
type: array
description: The devices installed in the vehicle.
items:
$ref: '#/components/schemas/DeviceId'
licensePlate:
type: object
properties:
state:
$ref: '#/components/schemas/State'
number:
type: string
example: ABC-1234
fuelType:
enum:
- gasoline
- diesel
- propane
- electric
- hybrid_gasoline
- hybrid_diesel
- biodiesel
- compressed_natural_gas
- liquefied_natural_gas
- ethanol
- hydrogen
- plug_in_hybrid
example: diesel
fuelEfficiency:
type: number
deprecated: true
description: This field will be removed in the future as is not commonly available from providers.
example: 27.4
fuelTankCapacity:
description: Maximum amount of fuel vehicle can hold in liters.
title: Volume In Liters
type: number
example: 95.33
createdAt:
$ref: '#/components/schemas/SourceCreatedAt'
updatedAt:
$ref: '#/components/schemas/SourceUpdatedAt'
metadata:
$ref: '#/components/schemas/CoreEntityMetadata'
raw:
$ref: '#/components/schemas/RawDataList'
required:
- id
- sourceId
- provider
- status
- metadata
x-description: The model representing a vehicle in Terminal.
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
EntityMetadata:
title: EntityMetadata
type: object
description: Internal metadata about the record.
required:
- addedAt
- modifiedAt
properties:
addedAt:
$ref: '#/components/schemas/AddedAt'
modifiedAt:
$ref: '#/components/schemas/ModifiedAt'
ExpandableVehicle:
example: vcl_01D8ZQFGHVJ858NBF2Q7DV9MNC
oneOf:
- $ref: '#/components/schemas/VehicleId'
- $ref: '#/components/schemas/ExpandedVehicle'
FaultCodeEvent:
title: Fault Code Event
x-model-category: time-series
x-read-permission: fault-codes:read
type: object
properties:
id:
$ref: '#/components/schemas/FaultCodeEventId'
provider:
$ref: '#/components/schemas/ProviderCode'
vehicle:
$ref: '#/components/schemas/ExpandableVehicle'
description: The vehicle associated with the fault.
protocol:
$ref: '#/components/schemas/FaultCodeProtocol'
status:
type: string
enum:
- open
- pending
- closed
description: The status of the fault code at the time of the event. Some providers do not report closed statuses.
code:
type: string
example: P0087
description: 'The fault code identifier. For OBD-II systems: alphanumeric DTC codes (P0087, U0046, C0123, B1234). For J1939 systems: SPN-FMI format (SPN3031-FMI9) or derived codes from SPN/FMI combinations.'
description:
type: string
example: Fuel Rail/System Pressure - Too Low Bank 1
description: Human-readable description of the fault
observedAt:
$ref: '#/components/schemas/ISODateTime'
description: The time the fault code was observed
milStatus:
type: string
enum:
- 'on'
- 'off'
description: The Malfunction Indicator Lamp (MIL) status of the vehicle at the time the fault code was observed
obdii:
type: object
description: OBD-II Diagnostic Trouble Code information for light/medium duty vehicles. Contains standardized alphanumeric codes like P0087, U0046, C0123, B1234.
properties:
code:
type: string
example: P0087
description: Alphanumeric DTC code (e.g., P0087, U0046)
description:
type: string
example: Fuel Rail/System Pressure - Too Low Bank 1
description: Human-readable description of the DTC
required:
- code
j1939:
type: object
description: J1939 fault code information for heavy-duty vehicles. FMI (Failure Mode Identifier) indicates the specific nature of the fault (0-31 numeric codes).
properties:
fmi:
type: integer
example: 9
description: Failure Mode Identifier (FMI) - numeric code (0-31) indicating the specific nature of the fault
fmiDescription:
type: string
example: Voltage Below Normal
description: Human-readable description of the FMI failure mode
spn:
type: integer
example: 3031
description: Suspect Parameter Number (SPN) - identifies the specific parameter/system affected
spnDescription:
type: string
example: 'System Diagnostic Code #1'
description: Human-readable description of the SPN parameter/system
occurrenceCount:
type: integer
example: 15
description: The occurrence count reported by the provider at the time the fault code was observed
sourceAddress:
type: integer
example: 256
description: The source address of the fault code
required:
- spn
metadata:
$ref: '#/components/schemas/EntityMetadata'
raw:
$ref: '#/components/schemas/RawDataList'
discriminator:
propertyName: protocol
oneOf:
- title: FaultCodeEventObdii
properties:
protocol:
const: obdii
required:
- protocol
- obdii
- title: FaultCodeEventJ1939
properties:
protocol:
const: j1939
required:
- protocol
- j1939
required:
- id
- provider
- vehicle
- code
- protocol
- observedAt
- status
- metadata
x-description: A fault code observed at a specific time
FaultCodeEventId:
title: FaultCodeEventId
type: string
format: ulid
example: fc_evt_01D8ZQFGHVJ858NBF2Q7DV9MNC
CoreEntityMetadata:
title: CoreEntityMetadata
type: object
description: Internal metadata about the record.
required:
- addedAt
- modifiedAt
properties:
addedAt:
$ref: '#/components/schemas/AddedAt'
modifiedAt:
$ref: '#/components/schemas/ModifiedAt'
deletedAt:
$ref: '#/components/schemas/DeletedAt'
visibility:
type: string
enum:
- visible
- hidden_by_exclude_list
- hidden_by_include_list
- hidden_by_status
- deleted
example: visible
description: Visibility status of a resource. Read more about hidden records [here](https://docs.withterminal.com/guides/vehicle-driver-filtering).
parameters:
Raw:
name: raw
in: query
required: false
schema:
type: boolean
description: Include raw responses used to normalize model. Used for debugging or accessing unique properties that are not unified.
ConnectionToken:
name: Connection-Token
in: header
required: true
schema:
type: string
example: con_tkn_22vUhkC6tgre4kwaYfUkCDA1rzn6eyb4
pattern: ^con_tkn_\S+$
description: The token returned when a user authenticated their account. This authorizes access to a specific account.
Limit:
name: limit
in: query
required: false
schema:
type: integer
description: The maximum number of results to return in a page.
ModifiedBefore:
name: modifiedBefore
in: query
required: false
schema:
type: string
format: date-time
example: '2021-01-06T03:24:53.000Z'
description: Only include records that were last modified before a provided date.
Cursor:
name: cursor
in: query
schema:
type: string
format: cursor
pattern: ^[A-Za-z0-9+/=_-]+$
example: cD0yMDIxLTAxLTA2KzAzJTNBMjQlM0E1My40MzQzMjYlMkIwMCUzQTAw
description: Pagination cursor to start requests from
VehicleIds:
name: vehicleIds
in: query
required: false
schema:
type: string
pattern: ^vcl_[0-9A-HJKMNP-TV-Z]{26}(\s*,\s*vcl_[0-9A-HJKMNP-TV-Z]{26})*$
description: Comma separated list of vehicle IDs to filter for. Can filter up to 50 vehicles at a time. Each ID must use the `vcl_` prefix.
ModifiedAfter:
name: modifiedAfter
in: query
required: false
schema:
type: string
format: date-time
example: '2021-01-06T03:24:53.000Z'
description: Only include records that were last modified after a provided date.
responses:
GoneError:
description: Gone
content:
application/json:
schema:
type: object
properties:
code:
enum:
- gone
- connection_deleted
example: connection_deleted
message:
type: string
example: Connection has been deleted and cannot be used
required:
- code
- message
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
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
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
securitySchemes:
Authorization:
type: http
scheme: bearer