API Reference

Base URL: https://fastcork.com

Authentication

All API requests require a Bearer token in the Authorization header.

Authorization: Bearer fc-your_api_key_here

Get a key: Purchase at fastcork.com/#pricing. Your API key is displayed on the dashboard immediately after payment.

Errors

Status	Meaning
401	Invalid or missing API key
402	Insufficient credits (pay-as-you-go)
500	Upstream error

Label Analysis

POST/v1/analyze

Analyze a wine label image and extract structured information. Accepts multipart/form-data.

Form fields

Field	Type	Description
file required	file	The wine label image (JPEG, PNG, WebP)
lang	string	Response language. Defaults to `zh` (Chinese) — pass `en` for English

Example

curl -X POST https://fastcork.com/v1/analyze \
  -H "Authorization: Bearer fc-your_key" \
  -F "file=@label.jpg" \
  -F "lang=en"

Wine Search

POST/v1/search

Natural language wine search with AI-powered recommendations.

Request body

Field	Type	Description
query required	string	Natural language query, e.g. `"bold reds under $30 for grilled lamb"`
lang	string	Response language. Defaults to `zh` (Chinese) — pass `en` for English

Example

curl -X POST https://fastcork.com/v1/search \
  -H "Authorization: Bearer fc-your_key" \
  -H "Content-Type: application/json" \
  -d '{
  "query": "bold reds under $30 for grilled lamb",
  "lang": "en"
}'

Sommelier Chat

POST/v1/chat

Multi-turn conversation with an AI sommelier. Send a sessionId to continue a conversation.

Request body

Field	Type	Description
message required	string	User message
sessionId	string	Omit to start a new session; include to continue
images	string[]	Optional array of raw base64 images (no data URI prefix) — wine labels, lists, or menus
lang	string	Response language. Defaults to `zh` — pass `en` for English

Example — new session

curl -X POST https://fastcork.com/v1/chat \
  -H "Authorization: Bearer fc-your_key" \
  -H "Content-Type: application/json" \
  -d '{
  "message": "What wine pairs well with duck confit?",
  "lang": "en"
}'

Response

{
  "sessionId": "abc123",
  "reply": {
    "type": "recommendation",
    "cards": [
      { "title": "Chateau Lafleur Pomerol", "subtitle": "Bordeaux, France", "badge": "Top pick" }
    ],
    "explanation": "Duck confit pairs beautifully with a silky Pomerol..."
  }
}

Delete Chat Session

DELETE/v1/chat/:sessionId

Delete a chat session and free server-side memory.

curl -X DELETE https://fastcork.com/v1/chat/abc123 \
  -H "Authorization: Bearer fc-your_key"