---
title: "Create Traceability Event"
method: POST
path: "/v1/farm/{farm_id}/traceability-events"
tags: ["traceability"]
---

# Create Traceability Event

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

## Request

- Base URL: `https://api.ranch.bot`
- URL: `https://api.ranch.bot/v1/farm/{farm_id}/traceability-events`
- Auth: HTTP bearer

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.

## Path parameters

- `farm_id` string, uuid, required

## Request body

- object
  - `request_key` string, required: Opaque idempotency key (1-200 characters).
  - `source` string, nullable
  - `payload` object, required: Versioned schema 1 traceability payload.

## Response `201`

Success

- object
  - `event` TraceabilityEvent, required
    - `id` string, required
    - `farm_id` string, required
    - `record_id` string, required
    - `kind` 'MOVEMENT' | 'PURCHASE' | 'SALE' | 'IMPORT' | 'EXPORT' | 'DEATH' | 'SLAUGHTER' | 'DISPOSAL' | 'IDENTIFICATION', required
    - `status` 'ACTIVE' | 'VOID', required
    - `current_revision` integer, required
    - `record` object
    - `revisions` object[]
    - `inventory_effects` object[]
    - `identifier_observations` object[]
    - `links_from` object[]
    - `links_to` object[]

## Other responses

- `400`: Validation failed.
- `401`: Missing/invalid authentication or role.
- `403`: Missing required credential scope.
- `404`: Not found.
- `409`: Conflict (stale version, reused key, or returned/void event).

---

[API](https://skmtc.dev/ranch/apis/ranch-bot-http-api.md) · [All operations](https://skmtc.dev/ranch/apis/ranch-bot-http-api/llms.txt) · [OpenAPI document](https://skmtc.dev/ranch/apis/ranch-bot-http-api/revisions/24109d33fa02?raw)