videographer.com · api

API reference

Turn a described shoot into a structured, priced request — and route it to real local videographers. Deterministic (no LLM), calibrated to real production rates. No key, no auth, free.

Quick start

Post a plain-language shoot description and get a structured request plus a calibrated budget estimate:

curl -s https://videographer.com/api/quote \
  -H 'content-type: application/json' \
  -d '{"description":"a 5-hour wedding in Austin, two cameras, drone"}'

Authentication

The pricing endpoints need no authentication. Creating a request with POST /api/order returns an owner token — a secret capability you pass back to broadcast or manage it. Write endpoints are rate-limited per IP.

Pricing

Describe a shoot → a structured request with a calibrated budget estimate.

POST/api/quote

Price a described shoot

Natural-language shoot description in, a structured request + calibrated budget estimate out. This is the engine behind the homepage builder.

Field	Type	Req	Description
`description`	string	yes	Plain-language shoot description.

Request

curl -s https://videographer.com/api/quote \
  -H 'content-type: application/json' \
  -d '{"description":"a 5-hour wedding in Austin, two cameras, drone"}'

Returns

200 A structured request and a budget estimate. QuoteResponse

Example response

{
  "order": {
    "shootType": "wedding",
    "city": "Austin",
    "cityTier": 3,
    "cityFactor": 1.05,
    "date": null,
    "durationMinutes": 300,
    "deliverableMinutes": null,
    "cameras": 2,
    "addons": [
      "drone"
    ],
    "budget": null,
    "budgetAmount": null
  },
  "estimate": {
    "currency": "USD",
    "range": {
      "low": 1675,
      "high": 3650
    },
    "display": "$1,675 – $3,650",
    "tiers": [
      {
        "key": "essentials",
        "label": "Essentials",
        "display": "$1,675 – $2,275",
        "includes": [
          "5h coverage",
          "2 cameras",
          "…"
        ]
      },
      {
        "key": "signature",
        "label": "Signature",
        "display": "$2,275 – $3,250",
        "includes": [
          "5h coverage",
          "2 cameras",
          "…"
        ]
      },
      {
        "key": "cinematic",
        "label": "Cinematic",
        "display": "$3,250 – $3,650",
        "includes": [
          "5h coverage",
          "2 cameras",
          "…"
        ]
      }
    ],
    "recommended": {
      "cameras": 2,
      "crew": 2,
      "coverageHours": 5,
      "deliverables": [
        "Raw footage (all coverage)",
        "Documentary edit option",
        "Highlight film (3–6 min)",
        "Color-graded delivery",
        "Aerial / drone"
      ],
      "turnaround": "4–8 weeks"
    },
    "lineItems": [
      {
        "label": "Wedding coverage + edit (raw → finished)",
        "low": 1150,
        "high": 2725
      },
      {
        "label": "Additional camera (×1)",
        "low": 200,
        "high": 200
      },
      {
        "label": "Aerial / drone",
        "low": 300,
        "high": 700
      }
    ],
    "assumptions": [
      "5h coverage",
      "2 cameras",
      "…"
    ],
    "note": "Estimate only — a real quote depends on the specific shoot, scope, and videographer. Ranges reflect real production pricing."
  }
}

POST/api/estimate

Price an already-structured request

If you already have a structured request (shoot type, city tier, duration, cameras, crew, add-ons), get just the budget estimate. Deterministic.

Field	Type	Req	Description
`shootType`	string · wedding \| corporate-event \| brand-film \| real-estate \| music-video \| other	—
`cityTier`	integer · 1 \| 2 \| 3	—	Cost band: 1 = highest-cost metros (SF/LA), 2 = major metros (Chicago/Boston/Seattle), 3 = standard markets. A finer per-city cityFactor is applied on top.
`durationMinutes`	integer	—
`cameras`	integer	—
`crew`	integer	—
`addons`	array	—	e.g. drone, second-shooter, same-day-edit.

Request

curl -s https://videographer.com/api/estimate \
  -H 'content-type: application/json' \
  -d '{"shootType":"wedding","cityTier":1,"durationMinutes":300,"cameras":2,"crew":1,"addons":["drone"]}'

Returns

200 The budget estimate.

Example response

{
  "estimate": {
    "currency": "USD",
    "range": {
      "low": 1675,
      "high": 3650
    },
    "display": "$1,675 – $3,650",
    "tiers": [
      {
        "key": "essentials",
        "label": "Essentials",
        "display": "$1,675 – $2,275",
        "includes": [
          "5h coverage",
          "2 cameras",
          "…"
        ]
      },
      {
        "key": "signature",
        "label": "Signature",
        "display": "$2,275 – $3,250",
        "includes": [
          "5h coverage",
          "2 cameras",
          "…"
        ]
      },
      {
        "key": "cinematic",
        "label": "Cinematic",
        "display": "$3,250 – $3,650",
        "includes": [
          "5h coverage",
          "2 cameras",
          "…"
        ]
      }
    ],
    "recommended": {
      "cameras": 2,
      "crew": 2,
      "coverageHours": 5,
      "deliverables": [
        "Raw footage (all coverage)",
        "Documentary edit option",
        "Highlight film (3–6 min)",
        "Color-graded delivery",
        "Aerial / drone"
      ],
      "turnaround": "4–8 weeks"
    },
    "lineItems": [
      {
        "label": "Wedding coverage + edit (raw → finished)",
        "low": 1150,
        "high": 2725
      },
      {
        "label": "Additional camera (×1)",
        "low": 200,
        "high": 200
      },
      {
        "label": "Aerial / drone",
        "low": 300,
        "high": 700
      }
    ],
    "assumptions": [
      "5h coverage",
      "2 cameras",
      "…"
    ],
    "note": "Estimate only — a real quote depends on the specific shoot, scope, and videographer. Ranges reflect real production pricing."
  }
}

Orders

Create a real, bookmarkable order and route it to matching videographers.

POST/api/order

Create a request

Create a real, bookmarkable order object from a described shoot. Returns an id and an owner token — keep the token to broadcast + manage the order.

Field	Type	Req	Description
`description`	string	yes	Plain-language shoot description.

Request

curl -s https://videographer.com/api/order \
  -H 'content-type: application/json' \
  -d '{"description":"brand film, half day, one location, Chicago"}'

Returns

200 The created order id + owner token.

Example response

{
  "id": "5a47a8f3-d3d4-4af8-99b1-f07c2abcb0ea",
  "token": "9c2f0b1e-4a77-4e2b-b0c1-7f3d2a1e6b84"
}

GET/api/order/{id}

Get order status

The live status of a request derived from its routes — open, routed, or accepted (with the accepting videographer once accepted).

Field	Type	Req	Description
`id`	string · path	yes

Request

curl -s https://videographer.com/api/order/{id}

Returns

200 The order status view. OrderStatus

Example response

{
  "id": "5a47a8f3-d3d4-4af8-99b1-f07c2abcb0ea",
  "created_at": "2026-07-24T18:02:11.904Z",
  "status": "open",
  "matchCount": 3,
  "routedCount": 0,
  "shootType": "wedding",
  "city": "Austin",
  "order": {
    "shootType": "wedding",
    "city": "Austin",
    "cityTier": 3,
    "cityFactor": 1.05,
    "date": null,
    "durationMinutes": 300,
    "deliverableMinutes": null,
    "cameras": 2,
    "addons": [
      "drone"
    ],
    "budget": null,
    "budgetAmount": null
  },
  "estimate": {
    "currency": "USD",
    "range": {
      "low": 1675,
      "high": 3650
    },
    "display": "$1,675 – $3,650",
    "tiers": [
      {
        "key": "essentials",
        "label": "Essentials",
        "display": "$1,675 – $2,275",
        "includes": [
          "5h coverage",
          "2 cameras",
          "…"
        ]
      },
      {
        "key": "signature",
        "label": "Signature",
        "display": "$2,275 – $3,250",
        "includes": [
          "5h coverage",
          "2 cameras",
          "…"
        ]
      },
      {
        "key": "cinematic",
        "label": "Cinematic",
        "display": "$3,250 – $3,650",
        "includes": [
          "5h coverage",
          "2 cameras",
          "…"
        ]
      }
    ],
    "recommended": {
      "cameras": 2,
      "crew": 2,
      "coverageHours": 5,
      "deliverables": [
        "Raw footage (all coverage)",
        "Documentary edit option",
        "Highlight film (3–6 min)",
        "Color-graded delivery",
        "Aerial / drone"
      ],
      "turnaround": "4–8 weeks"
    },
    "lineItems": [
      {
        "label": "Wedding coverage + edit (raw → finished)",
        "low": 1150,
        "high": 2725
      },
      {
        "label": "Additional camera (×1)",
        "low": 200,
        "high": 200
      },
      {
        "label": "Aerial / drone",
        "low": 300,
        "high": 700
      }
    ],
    "assumptions": [
      "5h coverage",
      "2 cameras",
      "…"
    ],
    "note": "Estimate only — a real quote depends on the specific shoot, scope, and videographer. Ranges reflect real production pricing."
  },
  "description": "a 5-hour wedding in Austin, two cameras, drone",
  "videographer": null,
  "isOwner": false
}

POST/api/order/{id}/broadcast

Broadcast a request to matching videographers

Route the order to matching local videographers (pull-model inbox). Requires the owner token. Idempotent — re-broadcasting a routed order is a no-op.

Field	Type	Req	Description
`id`	string · path	yes
`token`	string	yes	The owner token from create.

Request

curl -s https://videographer.com/api/order/{id}/broadcast \
  -H 'content-type: application/json' \
  -d '{}'

Returns

200 Routed count.

Example response

{
  "ok": true,
  "routed": 2
}

integrations

MCP server

Run the MCP server locally and point your client at it and your agent can price shoots and pull market costs directly — the same numbers the site uses. Tools: price_video_shoot, video_cost_by_market, list_video_markets.

{
  "mcpServers": {
    "videographer": {
      "command": "node",
      "args": ["/absolute/path/to/videographer.com/apps/com/app/mcp.js"]
    }
  }
}

Answer engines

Machine-readable endpoints and real cost data are published at /llms.txt for citation by LLMs, and the full contract is at /openapi.json.

Errors & rate limits

Errors return a JSON body { "error": "…" } with a 4xx status. Write endpoints (/api/quote, /api/order, broadcast) are throttled per client IP; exceeding the window returns 429.