Create a caravan

post/caravans

Creates a new caravan in forming status.

Request Body

required

application/json

namestringrequired

Human-readable caravan name

descriptionstring

Optional description of the caravan

routestring ("sahara_crossing" | "oasis_loop" | "silk_road_west" | "nile_delta" | "atlas_pass")

Assigned trade route

camel_countinteger

Number of camels assigned to the caravan

Responses

201Created

application/json

idstringrequired

Unique caravan identifier

namestringrequired

Human-readable caravan name

descriptionstring

Optional description of the caravan

routestring ("sahara_crossing" | "oasis_loop" | "silk_road_west" | "nile_delta" | "atlas_pass")

Assigned trade route

Current lifecycle status

camel_countinteger

Number of camels assigned to the caravan

lead_trader_namestring

Name of the trader responsible for the caravan

origin_marketstring

Market where the caravan begins its route

destination_marketstring

Primary market destination for the caravan

scheduled_departure_atstring (date-time)

Planned departure time for the caravan

estimated_arrival_atstring (date-time)

Estimated arrival time at the destination market

manifest_idstring

Active cargo manifest assigned to the caravan

created_atstring (date-time)required

When the caravan was created

updated_atstring (date-time)

When the caravan was last updated

Errors

Request

curl -X POST 'https://api.cameltrading.example/v1/caravans' \
  -H 'Authorization: Bearer <your-token>' \
  -H 'Content-Type: application/json' \
  -d '{
  "name": "Dune Pearl Caravan",
  "description": "A twelve-camel spice caravan bound for the western oasis markets",
  "route": "sahara_crossing",
  "camel_count": 12
}'

Response

{
  "id": "car_sahara_001",
  "name": "Dune Pearl Caravan",
  "description": "A twelve-camel spice caravan bound for the western oasis markets",
  "route": "sahara_crossing",
  "status": "ready",
  "camel_count": 12,
  "lead_trader_name": "Samira ibn Harun",
  "origin_market": "mkt_timbuktu",
  "destination_market": "mkt_marrakesh",
  "scheduled_departure_at": "2026-04-01T05:30:00Z",
  "estimated_arrival_at": "2026-04-09T18:00:00Z",
  "manifest_id": "man_amber_2026",
  "created_at": "2026-01-15T10:30:00Z",
  "updated_at": "2026-03-20T14:45:00Z"
}