AssetPilot Connect API keys, endpoints and errors

AssetPilot Connect provides API-key access to the AssetPilot for Jira API for scripts and internal tools. Connect is pre-release and requires AssetPilot's app REST API, which is not in production.

Pre-release

This page describes the release candidate. AssetPilot Connect is not on Atlassian Marketplace yet and requires AssetPilot 0.2.

API keys: the base URL, the OpenAPI document and one key per script. Host names are replaced with placeholders.

Access methods

There are two ways to call the same AssetPilot API (/v1/...):

Same paths and errors, two ways to authenticate.

	Connect API key	OAuth 2.0 (3LO)
Base URL	Connect's public API web trigger URL, shown on the API keys page	https://api.atlassian.com/svc/jira/<cloudId>/apps/<appId>_<envId>
Authentication	X-API-Key: apk_… header	Bearer access token with AssetPilot's custom scopes
Best for	Scripts and internal tools	Integrations that act as a user

The API keys page links to the OpenAPI document at <base URL>/v1/openapi.json.

API keys

1. Open API keys and select Create API key.
2. Name the key after the script or tool that uses it, for example Power BI reporting.
3. Tick only the scopes it needs: read, write and/or sync.
4. Select Create. The key is shown once, with a ready-to-run curl example. Copy it, then select I've copied it.

The key is shown once and stored only as a SHA-256 hash. You can revoke it at any time: requests with a revoked key fail right away with 401.

Key scope	Grants
read	Read assets, the catalog (types, locations, people, workflow) and events
write	Create, update and delete assets, change status, check out and check in
sync	Send devices to POST /v1/sync/devices

Each key allows 120 requests per minute by default, configurable to 30–600. Above the limit, Connect returns 429 with Retry-After.

curl -H "X-API-Key: $ASSETPILOT_KEY" "$CONNECT_API_URL/v1/assets?q=MacBook&pageSize=20"

Endpoints

Method	Path	Scope
GET	/v1/health	read
GET	/v1/assets, /v1/assets/{id or tag}	read
POST, PATCH, DELETE	/v1/assets, /v1/assets/{id or tag}	write
POST	/v1/assets/{id or tag}/status, /checkout, /checkin	write
GET	/v1/types, /v1/locations, /v1/people, /v1/workflow	read
GET	/v1/events, /v1/attention	read
POST	/v1/sync/devices	sync

List assets

GET /v1/assets accepts these query parameters and returns { items, total, page, pageSize }:

Parameter	Example
q	Search text: MacBook
typeId, statusId, locationId	Filter by id
category	Status category, such as in_use
assignee	unassigned, user:<accountId> or person:<id>
updatedSince	Only assets changed after a timestamp
sort	<key>:<asc or desc>
page, pageSize	1-based page; up to 200 per page, 50 by default

Events feed

GET /v1/events returns the AssetPilot audit events in order, for polling integrations. Pass after (the cursor from the previous page), limit (up to 200, 100 by default) and optionally kinds as a comma-separated list. The response is { items, cursor, hasMore }.

Write bodies

Endpoint	Body
POST /v1/assets/{id or tag}/status	{ "statusId": "…", "note": "…" }, note optional unless the status requires one
POST /v1/assets/{id or tag}/checkout	{ "assignee": { "kind": "user", "accountId": "…" } } or { "kind": "person", "personId": "…" }, plus optional dueDate, note, issueKey
POST /v1/assets/{id or tag}/checkin	Optional statusId, note, locationId

Errors

Every error has the body { "error": { "code": "…", "message": "…", "details": {} } }.

Code	HTTP	Meaning
VALIDATION_FAILED	400	The body or query is invalid. details names the fields.
UNAUTHENTICATED	401	Missing, unknown or revoked key
FORBIDDEN, LICENSE_INACTIVE	403	The key lacks the scope, or AssetPilot's licence is inactive
NOT_FOUND	404	No asset with that id or tag
TAG_TAKEN, SERIAL_TAKEN, ALREADY_CHECKED_OUT, NOT_CHECKED_OUT, TRANSITION_NOT_ALLOWED	409	The change conflicts with current data or the lifecycle
PAYLOAD_TOO_LARGE	413	Body over 800 kB
RATE_LIMITED	429	Over the key's limit. Wait for Retry-After.
ASSETPILOT_UNREACHABLE	502	AssetPilot did not answer
NOT_CONNECTED	503	Connect is not authorized with AssetPilot

Idempotency

Write requests may send Idempotency-Key: <1–255 printable ASCII characters>. Connect returns the stored response for a repeat within 24 hours, with the header Idempotent-Replayed: true.

curl -X POST "$CONNECT_API_URL/v1/assets/AP-00042/checkin" \
  -H "X-API-Key: $ASSETPILOT_KEY" \
  -H "Idempotency-Key: checkin-AP-00042-2026-10-18" \
  -H "Content-Type: application/json" \
  -d '{"note": "Returned to HQ"}'

See Permissions and Data and privacy before configuring access.