Traceability API

HTTP reference for traceability. Read authentication and access before using these operations. All examples use made-up data and placeholder credentials.

GET /v1/farm/{farm_id}/traceability-events
POST /v1/farm/{farm_id}/traceability-events
GET /v1/farm/{farm_id}/traceability-events/history
GET /v1/farm/{farm_id}/traceability-events/transport-suggestions
GET /v1/farm/{farm_id}/traceability-events/status/{request_key}
GET /v1/farm/{farm_id}/traceability-events/{event_id}
GET /v1/farm/{farm_id}/traceability-events/{event_id}/revisions
POST /v1/farm/{farm_id}/traceability-events/{event_id}/correct
POST /v1/farm/{farm_id}/traceability-events/{event_id}/void

GET /v1/farm/{farm_id}/traceability-events

List Traceability Events

List typed events; voided events are excluded unless include_void is true. Event/history/suggestion scopes use read:records/write:records; a payload that updates current animal identifiers or status additionally requires write:animals.

Parameter	In	Required	Schema
farm_id	path	Yes	{"type":"string","format":"uuid"}
skip	query	No	{"type":"integer"}
take	query	No	{"type":"integer"}
kind	query	No	{"type":"string","enum":["MOVEMENT","PURCHASE","SALE","IMPORT","EXPORT","DEATH","SLAUGHTER","DISPOSAL","IDENTIFICATION"]} Filter by typed event kind.
movement	query	No	{"type":"boolean"}
include_void	query	No	{"type":"boolean"}

Request example

bash example

curl --fail-with-body -X GET \
  'https://api.ranch.bot/v1/farm/<farm_id>/traceability-events' \
  -H "Authorization: Bearer $RANCHBOT_TOKEN"

Responses

Status	Meaning	Content type
200	Success	application/json
400	Validation failed.	No body
401	Missing/invalid authentication or role.	No body
403	Missing required credential scope.	No body
404	Not found.	No body
409	Conflict (stale version, reused key, or returned/void event).	No body

200 response schema (application/json)

Field	Type	Presence	Constraints
total	number	Required
events	array	Required
events[]	object	Required
events[].id	string	Required
events[].farm_id	string	Required
events[].record_id	string	Required
events[].kind	string	Required	enum: ["MOVEMENT","PURCHASE","SALE","IMPORT","EXPORT","DEATH","SLAUGHTER","DISPOSAL","IDENTIFICATION"]
events[].status	string	Required	enum: ["ACTIVE","VOID"]
events[].current_revision	integer	Required
events[].record	object	Optional
events[].revisions	array	Optional
events[].revisions[]	object	Required
events[].inventory_effects	array	Optional
events[].inventory_effects[]	object	Required
events[].identifier_observations	array	Optional
events[].identifier_observations[]	object	Required
events[].links_from	array	Optional
events[].links_from[]	object	Required
events[].links_to	array	Optional
events[].links_to[]	object	Required

POST /v1/farm/{farm_id}/traceability-events

Create Traceability Event

Create one typed event atomically with an idempotent request key. Event/history/suggestion scopes use read:records/write:records; a payload that updates current animal identifiers or status additionally requires write:animals.

Parameter	In	Required	Schema
farm_id	path	Yes	{"type":"string","format":"uuid"}

Request body (application/json)

Field	Type	Presence	Constraints
request_key	string	Required	minLength: 1; maxLength: 200
source (variant 1)	null	Optional
source (variant 2)	string	Optional
payload	object	Required

json example

{
  "request_key": "00000000-0000-4000-8000-000000000001",
  "payload": {
    "schema_version": 1,
    "kind": "SALE",
    "event_date": "2026-04-10",
    "populations": [
      {
        "line_id": "l1",
        "subject_type": "LIVE_ANIMALS",
        "declared_count": {
          "state": "RECORDED",
          "value": 35
        }
      }
    ],
    "movement": {
      "purpose": {
        "state": "RECORDED",
        "value": "SALE"
      },
      "sent": [
        {
          "line_id": "l1",
          "count": {
            "state": "RECORDED",
            "value": 35
          }
        }
      ]
    },
    "inventory_effects": [
      {
        "line_id": "l1",
        "effect": "REMOVE",
        "quantity": 35,
        "reason": "SALE"
      }
    ]
  }
}

Request example

bash example

curl --fail-with-body -X POST \
  'https://api.ranch.bot/v1/farm/<farm_id>/traceability-events' \
  -H "Authorization: Bearer $RANCHBOT_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"request_key":"00000000-0000-4000-8000-000000000001","payload":{"schema_version":1,"kind":"SALE","event_date":"2026-04-10","populations":[{"line_id":"l1","subject_type":"LIVE_ANIMALS","declared_count":{"state":"RECORDED","value":35}}],"movement":{"purpose":{"state":"RECORDED","value":"SALE"},"sent":[{"line_id":"l1","count":{"state":"RECORDED","value":35}}]},"inventory_effects":[{"line_id":"l1","effect":"REMOVE","quantity":35,"reason":"SALE"}]}}'

Responses

Status	Meaning	Content type
201	Success	application/json
400	Validation failed.	No body
401	Missing/invalid authentication or role.	No body
403	Missing required credential scope.	No body
404	Not found.	No body
409	Conflict (stale version, reused key, or returned/void event).	No body

201 response schema (application/json)

Field	Type	Presence	Constraints
event	object	Required
event.id	string	Required
event.farm_id	string	Required
event.record_id	string	Required
event.kind	string	Required	enum: ["MOVEMENT","PURCHASE","SALE","IMPORT","EXPORT","DEATH","SLAUGHTER","DISPOSAL","IDENTIFICATION"]
event.status	string	Required	enum: ["ACTIVE","VOID"]
event.current_revision	integer	Required
event.record	object	Optional
event.revisions	array	Optional
event.revisions[]	object	Required
event.inventory_effects	array	Optional
event.inventory_effects[]	object	Required
event.identifier_observations	array	Optional
event.identifier_observations[]	object	Required
event.links_from	array	Optional
event.links_from[]	object	Required
event.links_to	array	Optional
event.links_to[]	object	Required

GET /v1/farm/{farm_id}/traceability-events/history

Identifier History

Look up typed identifier observations by value across revisions. Event/history/suggestion scopes use read:records/write:records; a payload that updates current animal identifiers or status additionally requires write:animals.

Parameter	In	Required	Schema
farm_id	path	Yes	{"type":"string","format":"uuid"}
value	query	Yes	{"type":"string","minLength":1,"maxLength":128} Identifier string value to search (1-128 characters after trimming).
type	query	No	{"type":"string","maxLength":50} Optional free-form identifier type filter (50 characters or fewer after trimming).
include_historical	query	No	{"type":"boolean"}

Request example

bash example

curl --fail-with-body -X GET \
  'https://api.ranch.bot/v1/farm/<farm_id>/traceability-events/history?value=PLACEHOLDER_VALUE' \
  -H "Authorization: Bearer $RANCHBOT_TOKEN"

Responses

Status	Meaning	Content type
200	Success	application/json
400	Validation failed.	No body
401	Missing/invalid authentication or role.	No body
403	Missing required credential scope.	No body
404	Not found.	No body
409	Conflict (stale version, reused key, or returned/void event).	No body

200 response schema (application/json)

Field	Type	Presence
matches	array	Required
matches[]	object	Required
untyped	boolean	Required

GET /v1/farm/{farm_id}/traceability-events/transport-suggestions

Transport Suggestions

Bounded recent transporter/vehicle suggestions from current nonvoid revisions. The strict take limit is 1-100 and defaults to 20; offset pagination (skip) is not supported. Event, history, and suggestion reads use read:records; writes use write:records; a payload that updates current animal identifiers or status additionally requires write:animals.

Parameter	In	Required	Schema
farm_id	path	Yes	{"type":"string","format":"uuid"}
take	query	No	{"type":"integer","minimum":1,"maximum":100,"default":20} Maximum number of suggestions to return (1-100; defaults to 20).

Request example

bash example

curl --fail-with-body -X GET \
  'https://api.ranch.bot/v1/farm/<farm_id>/traceability-events/transport-suggestions' \
  -H "Authorization: Bearer $RANCHBOT_TOKEN"

Responses

Status	Meaning	Content type
200	Success	application/json
400	Validation failed.	No body
401	Missing/invalid authentication or role.	No body
403	Missing required credential scope.	No body
404	Not found.	No body
409	Conflict (stale version, reused key, or returned/void event).	No body

200 response schema (application/json)

Field	Type	Presence	Constraints
suggestions	array	Required
suggestions[]	object	Required

GET /v1/farm/{farm_id}/traceability-events/status/{request_key}

Write Status Reconciliation

Read-only reconciliation of a previously attempted event write. Event/history/suggestion scopes use read:records/write:records; a payload that updates current animal identifiers or status additionally requires write:animals.

Parameter	In	Required	Schema
farm_id	path	Yes	{"type":"string","format":"uuid"}
request_key	path	Yes	{"type":"string","minLength":1,"maxLength":200}

Request example

bash example

curl --fail-with-body -X GET \
  'https://api.ranch.bot/v1/farm/<farm_id>/traceability-events/status/<request_key>' \
  -H "Authorization: Bearer $RANCHBOT_TOKEN"

Responses

Status	Meaning	Content type
200	Success	application/json
400	Validation failed.	No body
401	Missing/invalid authentication or role.	No body
403	Missing required credential scope.	No body
404	Not found.	No body
409	Conflict (stale version, reused key, or returned/void event).	No body

200 response schema (application/json)

Field	Type	Presence
request_key	string	Required
event_id (variant 1)	null	Required
event_id (variant 2)	string	Required
revision (variant 1)	null	Required
revision (variant 2)	integer	Required
status (variant 1)	null	Required
status (variant 2)	string	Required

GET /v1/farm/{farm_id}/traceability-events/{event_id}

Get Traceability Event

Get one typed event with its current revision and projections. Event/history/suggestion scopes use read:records/write:records; a payload that updates current animal identifiers or status additionally requires write:animals.

Parameter	In	Required	Schema
farm_id	path	Yes	{"type":"string","format":"uuid"}
event_id	path	Yes	{"type":"string","format":"uuid"}

Request example

bash example

curl --fail-with-body -X GET \
  'https://api.ranch.bot/v1/farm/<farm_id>/traceability-events/<event_id>' \
  -H "Authorization: Bearer $RANCHBOT_TOKEN"

Responses

Status	Meaning	Content type
200	Success	application/json
400	Validation failed.	No body
401	Missing/invalid authentication or role.	No body
403	Missing required credential scope.	No body
404	Not found.	No body
409	Conflict (stale version, reused key, or returned/void event).	No body

200 response schema (application/json)

Field	Type	Presence	Constraints
event	object	Required
event.id	string	Required
event.farm_id	string	Required
event.record_id	string	Required
event.kind	string	Required	enum: ["MOVEMENT","PURCHASE","SALE","IMPORT","EXPORT","DEATH","SLAUGHTER","DISPOSAL","IDENTIFICATION"]
event.status	string	Required	enum: ["ACTIVE","VOID"]
event.current_revision	integer	Required
event.record	object	Optional
event.revisions	array	Optional
event.revisions[]	object	Required
event.inventory_effects	array	Optional
event.inventory_effects[]	object	Required
event.identifier_observations	array	Optional
event.identifier_observations[]	object	Required
event.links_from	array	Optional
event.links_from[]	object	Required
event.links_to	array	Optional
event.links_to[]	object	Required

GET /v1/farm/{farm_id}/traceability-events/{event_id}/revisions

Traceability Event Revisions

List every stored revision, including superseded and voided facts. Event/history/suggestion scopes use read:records/write:records; a payload that updates current animal identifiers or status additionally requires write:animals.

Parameter	In	Required	Schema
farm_id	path	Yes	{"type":"string","format":"uuid"}
event_id	path	Yes	{"type":"string","format":"uuid"}

Request example

bash example

curl --fail-with-body -X GET \
  'https://api.ranch.bot/v1/farm/<farm_id>/traceability-events/<event_id>/revisions' \
  -H "Authorization: Bearer $RANCHBOT_TOKEN"

Responses

Status	Meaning	Content type
200	Success	application/json
400	Validation failed.	No body
401	Missing/invalid authentication or role.	No body
403	Missing required credential scope.	No body
404	Not found.	No body
409	Conflict (stale version, reused key, or returned/void event).	No body

200 response schema (application/json)

Field	Type	Presence
event_id	string	Required
current_revision	integer	Required
status	string	Required
revisions	array	Required
revisions[]	object	Required

POST /v1/farm/{farm_id}/traceability-events/{event_id}/correct

Correct Traceability Event

Append a full replacement revision, rebuilding projections atomically. Event/history/suggestion scopes use read:records/write:records; a payload that updates current animal identifiers or status additionally requires write:animals.

Parameter	In	Required	Schema
farm_id	path	Yes	{"type":"string","format":"uuid"}
event_id	path	Yes	{"type":"string","format":"uuid"}

Request body (application/json)

Field	Type	Presence	Constraints
request_key	string	Required	minLength: 1; maxLength: 200
expected_revision	integer	Required
reason	string	Required
source (variant 1)	null	Optional
source (variant 2)	string	Optional
payload	object	Required

json example

{
  "request_key": "00000000-0000-4000-8000-000000000002",
  "expected_revision": 1,
  "reason": "Corrected the destination",
  "payload": {
    "schema_version": 1,
    "kind": "MOVEMENT",
    "event_date": "2026-04-10",
    "populations": [
      {
        "line_id": "l1",
        "subject_type": "LIVE_ANIMALS",
        "declared_count": {
          "state": "RECORDED",
          "value": 5
        }
      }
    ]
  }
}

Request example

bash example

curl --fail-with-body -X POST \
  'https://api.ranch.bot/v1/farm/<farm_id>/traceability-events/<event_id>/correct' \
  -H "Authorization: Bearer $RANCHBOT_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"request_key":"00000000-0000-4000-8000-000000000002","expected_revision":1,"reason":"Corrected the destination","payload":{"schema_version":1,"kind":"MOVEMENT","event_date":"2026-04-10","populations":[{"line_id":"l1","subject_type":"LIVE_ANIMALS","declared_count":{"state":"RECORDED","value":5}}]}}'

Responses

Status	Meaning	Content type
200	Success	application/json
400	Validation failed.	No body
401	Missing/invalid authentication or role.	No body
403	Missing required credential scope.	No body
404	Not found.	No body
409	Conflict (stale version, reused key, or returned/void event).	No body

200 response schema (application/json)

Field	Type	Presence	Constraints
event	object	Required
event.id	string	Required
event.farm_id	string	Required
event.record_id	string	Required
event.kind	string	Required	enum: ["MOVEMENT","PURCHASE","SALE","IMPORT","EXPORT","DEATH","SLAUGHTER","DISPOSAL","IDENTIFICATION"]
event.status	string	Required	enum: ["ACTIVE","VOID"]
event.current_revision	integer	Required
event.record	object	Optional
event.revisions	array	Optional
event.revisions[]	object	Required
event.inventory_effects	array	Optional
event.inventory_effects[]	object	Required
event.identifier_observations	array	Optional
event.identifier_observations[]	object	Required
event.links_from	array	Optional
event.links_from[]	object	Required
event.links_to	array	Optional
event.links_to[]	object	Required

POST /v1/farm/{farm_id}/traceability-events/{event_id}/void

Void Traceability Event

Void a typed event with a reason; history keeps every revision. Event/history/suggestion scopes use read:records/write:records; a payload that updates current animal identifiers or status additionally requires write:animals.

Parameter	In	Required	Schema
farm_id	path	Yes	{"type":"string","format":"uuid"}
event_id	path	Yes	{"type":"string","format":"uuid"}

Request body (application/json)

Field	Type	Presence	Constraints
request_key	string	Required	minLength: 1; maxLength: 200
expected_revision	integer	Required
reason	string	Required

json example

{
  "request_key": "00000000-0000-4000-8000-000000000003",
  "expected_revision": 1,
  "reason": "Duplicate entry"
}

Request example

bash example

curl --fail-with-body -X POST \
  'https://api.ranch.bot/v1/farm/<farm_id>/traceability-events/<event_id>/void' \
  -H "Authorization: Bearer $RANCHBOT_TOKEN" \
  -H "Content-Type: application/json" \
  --data '{"request_key":"00000000-0000-4000-8000-000000000003","expected_revision":1,"reason":"Duplicate entry"}'

Responses

Status	Meaning	Content type
200	Success	application/json
400	Validation failed.	No body
401	Missing/invalid authentication or role.	No body
403	Missing required credential scope.	No body
404	Not found.	No body
409	Conflict (stale version, reused key, or returned/void event).	No body

200 response schema (application/json)

Field	Type	Presence	Constraints
event	object	Required
event.id	string	Required
event.farm_id	string	Required
event.record_id	string	Required
event.kind	string	Required	enum: ["MOVEMENT","PURCHASE","SALE","IMPORT","EXPORT","DEATH","SLAUGHTER","DISPOSAL","IDENTIFICATION"]
event.status	string	Required	enum: ["ACTIVE","VOID"]
event.current_revision	integer	Required
event.record	object	Optional
event.revisions	array	Optional
event.revisions[]	object	Required
event.inventory_effects	array	Optional
event.inventory_effects[]	object	Required
event.identifier_observations	array	Optional
event.identifier_observations[]	object	Required
event.links_from	array	Optional
event.links_from[]	object	Required
event.links_to	array	Optional
event.links_to[]	object	Required

Error body

Validation and authentication errors generally use this envelope. Rate-limit errors omit data; OAuth polling also has protocol-specific errors shown in its reference.

json example

{
  "success": false,
  "errors": [
    {
      "code": 400,
      "name": "ValidationError",
      "message": "Example validation failure"
    }
  ]
}