Developers

API Keys

Contract-backed public API reference for bearer-key authentication and currently supported endpoints.

Overview

Contract reference

Generated from the same OpenAPI document the application serves. Default environment is sandbox; switching to production requires an intentional opt-in.

Field	Value
Source	generated-openapi-prefix-parity
Sandbox key prefix	`arcv_sandbox_`
Production key prefix	`arcv_live_`
Sandbox base URL	`https://arcova_ai.test/api/v1`
Production base URL	`https://arcova_ai.test/api/v1`

Only switch to production credentials after sandbox validation and response-shape verification pass.

Setup

Authentication headers

Header	Value	Required
`Authorization`	`Bearer arcv_sandbox_your_key`	Yes
`Accept`	`application/json`	Yes
`X-Idempotency-Key`	`sandbox-request-001`	No

Endpoint

List incidents

GET/api/v1/incidents

Success response

200 — Paginated set of `IncidentApiResource`

Fields: datalinksmeta

Sandbox curl

curl -X GET "https://arcova_ai.test/api/v1/incidents" \
  -H "Authorization: Bearer arcv_sandbox_your_key" \
  -H "Accept: application/json" \
  -H "X-Idempotency-Key: sandbox-request-001"

Production curl (intentional switch only)

Only switch to production credentials after sandbox validation and response-shape verification pass.

curl -X GET "https://arcova_ai.test/api/v1/incidents" \
  -H "Authorization: Bearer arcv_live_your_key" \
  -H "Accept: application/json" \
  -H "X-Idempotency-Key: sandbox-request-001"

Common failures

Status	Reason
401	Missing or invalid API key.
403	API key scope does not allow this operation.

Endpoint

Create incident

POST/api/v1/incidents

Request parameters

Name	Type	Required	Description
`incident_type`	string	Yes	Incident classification code (e.g., `trespassing`, `medical_emergency`, `theft`). Determines workflow routing and required fields.
`subject`	string	Yes	Short incident title. Appears in lists and notification emails.
`narrative`	string	Yes	Detailed description of the event including what happened, who was involved, and how the situation was resolved.
`occurred_at`	string	Yes	ISO-8601 timestamp of when the incident occurred. Cannot be in the future.
`severity`	string	Yes	Severity level. Determines escalation rules and notification urgency. One of `low`, `medium`, `high`, `critical`.
`incident_category`	string	No	Broad category for grouping incidents in reports (e.g., `security`, `safety`, `property`).
`source`	string	No	How the incident was reported. Defaults to `api` when submitted via this endpoint.
`reporter_type`	string	No	Who filed the report. Defaults to `system` for API-created incidents.
`site_id`	integer\|null	No	Client site where the incident occurred. Must belong to the API key's location.
`location_description`	string\|null	No	Free-text location description when `site_id` is not available (e.g., "parking lot B, near east entrance").
`latitude`	number\|null	No	GPS latitude of the incident location.
`longitude`	number\|null	No	GPS longitude of the incident location.
`building`	string\|null	No	Building name or number.
`floor`	string\|null	No	Floor or level within the building.
`unit_number`	string\|null	No	Unit or suite number.
`common_area`	string\|null	No	Common area name (e.g., "lobby", "pool deck", "loading dock").
`actions_taken`	string\|null	No	Description of actions taken by the officer or responding party at the scene.
`disposition`	string\|null	No	Final disposition or outcome of the incident (e.g., "suspect detained", "false alarm").
`law_enforcement_contacted`	boolean\|null	No	Whether law enforcement was contacted about the incident.
`law_enforcement_agency`	string\|null	No	Name of the law enforcement agency contacted.
`case_number`	string\|null	No	Police case or report number assigned by the responding agency.
`officer_name`	string\|null	No	Name of the responding law enforcement officer.
`officer_badge`	string\|null	No	Badge number of the responding officer.
`injuries_reported`	boolean\|null	No	Whether any injuries were reported as a result of the incident.
`injury_details`	string\|null	No	Description of injuries sustained, treatment provided, and transport details if applicable.
`property_damage`	boolean\|null	No	Whether property damage occurred during the incident.
`damage_details`	string\|null	No	Description of the damage including affected items and their condition.
`damage_estimate`	number\|null	No	Estimated cost of property damage in the location's currency.
`weather_conditions`	string\|null	No	Weather conditions at the time of the incident (e.g., "clear", "rain", "fog").
`temperature`	number\|null	No	Temperature in Fahrenheit at the time of the incident.
`occurred_timezone`	string\|null	No	IANA timezone of the occurrence (e.g., `America/New_York`). Used to display local time in reports.

Success response

201 — Successful response

Fields: messagedata

Sandbox curl

curl -X POST "https://arcova_ai.test/api/v1/incidents" \
  -H "Authorization: Bearer arcv_sandbox_your_key" \
  -H "Accept: application/json" \
  -H "X-Idempotency-Key: sandbox-request-001"

Production curl (intentional switch only)

Only switch to production credentials after sandbox validation and response-shape verification pass.

curl -X POST "https://arcova_ai.test/api/v1/incidents" \
  -H "Authorization: Bearer arcv_live_your_key" \
  -H "Accept: application/json" \
  -H "X-Idempotency-Key: sandbox-request-001"

Common failures

Status	Reason
401	Missing or invalid API key.
403	API key scope does not allow this operation.

Endpoint

Get incident statistics

GET/api/v1/incidents/stats

Success response

200 — Successful response

Fields: data

Sandbox curl

curl -X GET "https://arcova_ai.test/api/v1/incidents/stats" \
  -H "Authorization: Bearer arcv_sandbox_your_key" \
  -H "Accept: application/json" \
  -H "X-Idempotency-Key: sandbox-request-001"

Production curl (intentional switch only)

Only switch to production credentials after sandbox validation and response-shape verification pass.

curl -X GET "https://arcova_ai.test/api/v1/incidents/stats" \
  -H "Authorization: Bearer arcv_live_your_key" \
  -H "Accept: application/json" \
  -H "X-Idempotency-Key: sandbox-request-001"

Common failures

Status	Reason
401	Missing or invalid API key.
403	API key scope does not allow this operation.

Endpoint

Get incident

GET/api/v1/incidents/{uuid}

Request parameters

Name	Type	Required	Description
`uuid`	string	Yes

Success response

200 — `IncidentApiResource`

Fields: data

Sandbox curl

curl -X GET "https://arcova_ai.test/api/v1/incidents/{uuid}" \
  -H "Authorization: Bearer arcv_sandbox_your_key" \
  -H "Accept: application/json" \
  -H "X-Idempotency-Key: sandbox-request-001"

Production curl (intentional switch only)

Only switch to production credentials after sandbox validation and response-shape verification pass.

curl -X GET "https://arcova_ai.test/api/v1/incidents/{uuid}" \
  -H "Authorization: Bearer arcv_live_your_key" \
  -H "Accept: application/json" \
  -H "X-Idempotency-Key: sandbox-request-001"

Common failures

Status	Reason
401	Missing or invalid API key.
403	API key scope does not allow this operation.

Endpoint

Update incident

PATCH/api/v1/incidents/{uuid}

Request parameters

Name	Type	Required	Description
`uuid`	string	Yes
`incident_type`	string	No	Incident classification code (e.g., `trespassing`, `medical_emergency`, `theft`).
`subject`	string	No	Short incident title.
`narrative`	string	No	Detailed description of the event.
`occurred_at`	string	No	ISO-8601 timestamp of when the incident occurred. Cannot be in the future.
`severity`	string	No	Severity level (`low`, `medium`, `high`, `critical`).
`incident_category`	string	No	Broad category for grouping incidents in reports.
`site_id`	integer\|null	No	Client site where the incident occurred. Must belong to the API key's location.
`location_description`	string\|null	No	Free-text location description.
`latitude`	number\|null	No	GPS latitude.
`longitude`	number\|null	No	GPS longitude.
`building`	string\|null	No	Building name or number.
`floor`	string\|null	No	Floor or level within the building.
`unit_number`	string\|null	No	Unit or suite number.
`common_area`	string\|null	No	Common area name (e.g., "lobby", "pool deck").
`actions_taken`	string\|null	No	Description of actions taken by the officer or responding party.
`disposition`	string\|null	No	Final disposition or outcome of the incident.
`law_enforcement_contacted`	boolean	No	Whether law enforcement was contacted.
`law_enforcement_agency`	string\|null	No	Name of the law enforcement agency contacted.
`case_number`	string\|null	No	Police case or report number.
`officer_name`	string\|null	No	Name of the responding officer.
`officer_badge`	string\|null	No	Badge number of the responding officer.
`injuries_reported`	boolean	No	Whether any injuries were reported.
`injury_details`	string\|null	No	Description of injuries sustained and treatment provided.
`property_damage`	boolean	No	Whether property damage occurred.
`damage_details`	string\|null	No	Description of the damage.
`damage_estimate`	number\|null	No	Estimated cost of property damage.
`weather_conditions`	string\|null	No	Weather conditions at the time (e.g., "clear", "rain", "fog").
`temperature`	number\|null	No	Temperature in Fahrenheit at the time of the incident.
`occurred_timezone`	string\|null	No	IANA timezone of the occurrence (e.g., `America/New_York`).
`resolution_notes`	string\|null	No	Notes explaining how the incident was resolved. Used when closing an incident.

Success response

200 — `IncidentApiResource`

Fields: data

Sandbox curl

curl -X PATCH "https://arcova_ai.test/api/v1/incidents/{uuid}" \
  -H "Authorization: Bearer arcv_sandbox_your_key" \
  -H "Accept: application/json" \
  -H "X-Idempotency-Key: sandbox-request-001"

Production curl (intentional switch only)

Only switch to production credentials after sandbox validation and response-shape verification pass.

curl -X PATCH "https://arcova_ai.test/api/v1/incidents/{uuid}" \
  -H "Authorization: Bearer arcv_live_your_key" \
  -H "Accept: application/json" \
  -H "X-Idempotency-Key: sandbox-request-001"

Common failures

Status	Reason
401	Missing or invalid API key.
403	API key scope does not allow this operation.

Reference

Shared failure patterns

Status	Reason
401	Missing or invalid API key.
403	API key scope does not allow this operation.

Reference

Error response format

All error responses follow a consistent shape with an error code, message, and optional detail.

{
  "error": {
    "code": "invalid_api_key",
    "message": "The provided API key is invalid or has been revoked.",
    "detail": "Key arcv_sbx_abc123 was revoked at 2024-01-15T10:30:00Z"
  }
}

Status codes

Status	Code	Meaning	Action
401	`invalid_api_key`	Key revoked or malformed	Regenerate key
403	`insufficient_scope`	Missing permission	Add scope to key
404	`not_found`	Resource does not exist	Check resource ID
422	`validation_error`	Request body invalid	Check error.detail
429	`rate_limited`	Too many requests	Implement backoff
500	`internal_error`	Server error	Retry with backoff

Reference

Pagination

List endpoints return paginated results with page-based navigation.

GET /api/v1/incidents?page=1&per_page=15

Response:
{
  "data": [...],
  "meta": {
    "current_page": 1,
    "per_page": 15,
    "total": 100,
    "last_page": 7
  },
  "links": {
    "first": "/api/v1/incidents?page=1",
    "last":  "/api/v1/incidents?page=7",
    "next":  "/api/v1/incidents?page=2",
    "prev":  null
  }
}

page (query) — Page number, default 1.
per_page (query) — Items per page, default 15, max 100.

Reference

Rate limiting

All endpoints are rate limited per API key. The default limit is 60 requests per minute and may vary by endpoint.

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1700000060

When rate limited, the API returns HTTP 429 with a retry_after value in seconds.