Grapes, programmatically

Authentication

Authenticate with a bearer token. Enterprise customers receive keys from their grape success manager, in person, sealed in an envelope inside a slightly larger envelope.

curl https://api.monogrape.example/v1/grapes \
  -H "Authorization: Bearer mg_live_a1b2c3..."

POST/v1/grapes

Dispatches one grape. The quantity field exists for developer comfort and accepts only the value 1.

curl -X POST https://api.monogrape.example/v1/grapes \
  -H "Authorization: Bearer mg_live_a1b2c3..." \
  -H "Content-Type: application/json" \
  -d '{
    "quantity": 1,
    "varietal": "concord_classic",
    "chill": "standard",
    "destination": {
      "line1": "500 Startup Way, Floor 4",
      "city": "San Francisco",
      "notes": "Recipient may cry. This is normal."
    }
  }'

Response:

{
  "id": "grape_8Xk2mQ",
  "object": "grape.delivery",
  "status": "picking",
  "varietal": "concord_classic",
  "firmness_score": null,
  "eta_minutes": 24,
  "tissue_layers": 4,
  "tracking_url": "https://monogrape.example/t/MG-482910"
}

GET/v1/grapes/{id}

Returns the current state of a grape. States progress through picking, inspecting, nestling, en_route, and delivered. A sixth state, eaten_by_courier, was removed from the schema in v2 following the incident.

curl https://api.monogrape.example/v1/grapes/grape_8Xk2mQ \
  -H "Authorization: Bearer mg_live_a1b2c3..."

Webhooks

Subscribe to grape lifecycle events. Payloads are signed, because someone will absolutely spoof a grape.

Event	Fires when
grape.picked	Your grape leaves the vine
grape.inspected	Firmness score is recorded
grape.en_route	Courier begins the journey
grape.delivered	Handoff choreography completes
tissue.rustled	Beta. Requires the emotions add-on.

Rate limits

The API accepts 60 requests per minute and, by design, one grape per request. There is no batch endpoint. There will never be a batch endpoint. The CTO has a tattoo about this.

Errors

Code	Meaning
422	quantity was not 1. Please reflect.
409	You already have a grape in flight. Savor it.
451	Destination is inside a vineyard. We found this insulting.
503	Brunch surge. Retry after mimosas.