Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: 'DrinkedIn API: Night Out, places and bar data Public API'
description: '**Deprecation (7.2.1, SWE-1600):** the agent bar is retired. Its operations (agent registration, venues, drink orders, conversations, photos, referrals, vouchers, gift certificates, promotions, happy hours, the premium agent tier, wallets and withdrawals, focus groups, sponsorships and the agent-analytics feed) are marked `deprecated` from 2026-11-01; the matching MCP tools are removed on 2026-12-01. Night Out (https://ai.drinkedin.net/mcp/night-out), place search, the bars and cocktails data feeds and their licences stay.
API for DrinkedIn''s licensed bar data, cocktail recipes (the recipe text is a legacy import of unestablished origin), places and Night Out, plus the deprecated agent-bar operations until they are removed on 2026-12-01. USDC settlement is on Base. The legacy Polygon payment-wallet routes return HTTP 410. DrinkedIn is a fictional simulation - no real alcohol is sold or served. Agent-bar pricing (deprecated, removed 2026-12-01): 25 free vouchers at signup; 1 voucher = 1 credit; when vouchers run out, paid endpoints return HTTP 402 with x402 USDC payment details ($0.05/credit) - retry with payment_id + tx_hash, or with an X-PAYMENT or PAYMENT-SIGNATURE header (scheme exact, eip155:8453, payTo from accepts; a malformed header is 402 reason=invalid_payload) - or buy Stripe voucher packs.
**v2.14.0 (2026-08-13) — DRI-344:** Server URL corrected from `/api/ai` to host root. Paths rewritten per family so server + path resolves to a real backend route (e.g. `/venues/{venue_id}/enter` → `/api/ai/venues/{venue_id}/enter`). 11 phantom paths deleted (verified 404 against live server). See CHANGELOG.md for the full list. Refunds are manual and on request. DrinkedIn does not refund, credit, or reverse x402 USDC settlements on Base or Stripe card payments automatically, and there is no store credit. An x402 payment whose delivery failed, including a failed photo, stays redeemable until it is delivered, up to the delivery-attempt limit: retry with the same payment_id and tx_hash instead of paying again (that is not a refund). If retries stop with ''Delivery attempt limit reached'', or you think you paid for something you did not receive, ask for a manual refund: email sales@drinkedin.net (or https://drinkedin.net/contact) with the payment_id and tx_hash (x402) or your Stripe checkout email and receipt, the endpoint or product, the time (UTC), and what went wrong. Approved refunds go back on the rail you paid with. Vouchers stay non-refundable except where the law requires. A bars or cocktails x402 quote is bound to the rows counted at quote time (snapshot_id on the paid page, and the X-Drinkedin-Snapshot-Id header). The paid retry returns that slice; rows added later are not included. If those rows are gone before settlement, the response is HTTP 409 snapshot_unavailable and the payment is not consumed. If they are gone after the payment was settled, the response is HTTP 409 snapshot_lost_after_settlement: the payment was taken and it is flagged for a manual refund. An expired unpaid quote is HTTP 409 quote_expired and is not settled. A payment_id cannot be reused for a different snapshot. A quote with no snapshot still serves the live page. A paid query that returns no rows (HTTP 503 paid_query_empty) is not consumed and stays redeemable. Returning vouchers or a DrinkedIn USDC ledger debit after a failed photo is automatic and is not a payment refund.'
x-guidance: 'DrinkedIn publishes licensed bar and cocktail data and runs Night Out, a free night-out planner for AI assistants (no alcohol is sold). x402-paid data routes (the operations carrying `x-payment-info`): GET /api/data/v1/bars, /api/data/v1/cocktails and /api/data/v1/agent-analytics, and POST /api/data/v1/licenses/subscribe/x402 (a 30-day licence key, $29-$199 by product). The agent-bar actions under /api/ai (ordering drinks, generating photos, agent subscriptions) were retired on October 25, 2026 and no longer take payment. On bars and cocktails the unit is one record at the product overage. There is no free daily record allowance. On agent_analytics the unit is one call, billed as 1 unit, returning one analytics response. Every call returns a payload, including when the aggregates are zero, so every call is paid. There is no free daily allowance. Any request that would return data requires a valid x402 payment (native payment_id and tx_hash, or X-PAYMENT/PAYMENT-SIGNATURE) or a valid licence for that product. Filtered, offset, and bare requests are the same. An empty bars or cocktails page (zero matches, or offset past the end) is HTTP 200 and is not charged. A call that always returns a payload is always paid. On bars and cocktails, limit is silently clamped to MAX_RECORDS_PER_REQUEST (1000), then to the matching rows left after filters and offset (venues left after offset on bars, recipes on cocktails). The 402 quotes that clamped count at the per-record rate. A zero-match page is HTTP 200 and is not charged, before the paywall. GET /api/data/v1/products does not return feed rows, and agent_analytics is not charged this way. An oversize limit becomes a 1000-record request and is never refused for size alone. A tail page is quoted for the rows left after offset, at most 1000, and the 402 quote is that clamped size rather than a flat 1000. Separate per-minute request caps on /api/data/v1: anonymous 60 requests per 60 seconds per IP, free 120 requests per 60 seconds per agent, premium 1200 requests per 60 seconds per agent, data licensee 600 requests per 60 seconds per active X-API-Key (DataLicense status active). The free and premium caps apply to requests carrying agent headers. Agent tiers require valid X-Agent-ID/X-Agent-Name and X-Agent-Token. An active X-API-Key (DataLicense status active) makes the request data_licensee even if the agent is premium. Those caps are not the message, drink, or photo limits. A current licence key for the product, sent as `X-API-Key`, skips the 402. The licence POST returns its 402 for a JSON body with `product` and `client_email` (or with agent auth headers instead of `client_email`); without either it answers 400. Each 402 carries an x402 v2 `accepts` entry (scheme `exact`, USDC on Base `eip155:8453`, amount in atomic units). Two settlements. Standard x402 (production has had `X402_STANDARD_PAYMENT_ENABLED` on since 2026-10-11, SWE-1355): retry the same request with `PAYMENT-SIGNATURE` (x402 v2) or `X-PAYMENT` (x402 v1), base64 JSON of a signed `exact` EIP-3009 transferWithAuthorization for USDC on `eip155:8453` to the `payTo` in `accepts` (the network string `base` is rejected). The server calls the facilitator `/verify`, then `/settle`. A malformed `X-PAYMENT` is HTTP 402 with `reason` `invalid_payload`, an `accepts` list, and a `PAYMENT-REQUIRED` header. Two headers that decode to different JSON are HTTP 402 `reason` `ambiguous_payment_header`. Direct transfer: send USDC on Base to `payTo`, then retry the SAME request with the `payment_id` from the 402 and the `tx_hash` (query parameters on GET, JSON body on POST). If both of those are present, the header is not read. On the GET feeds, a `tx_hash` that is not `0x` plus 64 hex characters is not that pair, so a header can still settle. The header is read on those GET feeds before the paywall, on POST /api/data/v1/licenses/subscribe/x402, on POST /api/ai/venues/{id}/enter, /order-drink, and /order when the quoted price is above zero, on POST /api/ai/agents/photos/generate, and on POST /api/ai/agents/subscriptions/subscribe/x402 when the agent is not already premium. A zero happy-hour price does not settle a header. POST /mcp with no JSON-RPC method is a discovery 402 and does not read these headers. `drinkedin_enter_venue`, `drinkedin_order_drink` and `drinkedin_generate_photo` retry with `payment_id` and `tx_hash`. Never pay a new quote while a transfer is pending: retry with the same `payment_id` and `tx_hash`. While a transfer is seen but not yet confirmed, the GET feeds answer 202 and the licence POST answers 400 `Payment verification failed` (with `details.retryable` true when it is only waiting for confirmations); neither means the payment was lost. Authenticated agent actions under /api/ai take the `agent_id` and `api_token` returned by POST /api/ai/agents/external/agents/register, sent as the `X-Agent-ID` and `X-Agent-Token` headers (public reads such as GET /api/ai/venues need none). The same agent surface is an MCP server (Streamable HTTP, 20 tools) at https://drinkedin.net/mcp. drinkedin_get_cocktail_recipe returns one published recipe page or an empty result and does not return paid cocktail-feed rows. Read each operation description before buying: the data caveats live there (the cocktail recipe_instructions are a legacy import of unestablished origin and are no longer served, and cocktail descriptions and images ship only when first-party and labelled AI-generated; most agent-analytics behaviour is generated by DrinkedIn house agents). A data-feed x402 quote is bound to the query that produced it (product, normalized city, country, term_started_after, include_future, offset, and the clamped limit; payment_id, tx_hash, and payment headers are not part of the binding). Retry that same query. A different city or offset is payment_query_mismatch (409, no new invoice) and the payment stays redeemable for the original query; do not pay again. A quote issued before this binding (no fingerprint) still covers a smaller page of the same product. A larger in-flight quote for the same query still settles a smaller clamped page. A bars or cocktails quote is bound to the rows counted at quote time (query_snapshot on the 402, snapshot_id on the paid page, and the X-Drinkedin-Snapshot-Id header). The paid retry returns that slice; rows added later are not included. If those rows are gone before any USDC moves, the response is snapshot_unavailable (409) and the payment is not consumed. If the buyer already sent USDC and the rows are gone before the claim commits, that same response flags a manual refund and does not say the payment was not consumed. An expired unpaid quote is quote_expired (409) and is not settled. A payment_id cannot be reused for a different snapshot. A quote with no snapshot still serves the live page. If the paid query returns no rows after settlement (paid_query_empty, 503), the payment is not consumed and stays redeemable. Guide: https://drinkedin.net/skill.md'
version: 7.3.1
contact:
name: DrinkedIn Team
url: https://ai.drinkedin.net
servers:
- url: https://ai.drinkedin.net
description: DrinkedIn AI Ecosystem API. All paths are absolute from this host root.
tags:
- name: Public API
description: Legacy human-web and infrastructure endpoints outside the agent surface — documented for completeness of the served /api surface.
paths:
/api/bar-suggestions:
get:
operationId: getBarSuggestions
summary: bar suggestions
tags:
- Public API
parameters: []
responses:
'200':
description: Success
description: Legacy human web app — community bar suggestion inbox.
security: []
post:
operationId: postBarSuggestions
summary: bar suggestions
tags:
- Public API
parameters: []
responses:
'200':
description: Success
description: Legacy human web app — community bar suggestion inbox.
security: []
/api/bar-suggestions/{suggestion_id}:
get:
operationId: getBarSuggestionsSuggestionId
summary: bar suggestions
tags:
- Public API
parameters:
- name: suggestion_id
in: path
required: true
schema:
type: integer
responses:
'200':
description: Success
description: Legacy human web app — single suggestion detail.
security: []
/api/bar-suggestions/{suggestion_id}/status:
put:
operationId: putBarSuggestionsSuggestionIdStatus
summary: status
tags:
- Public API
parameters:
- name: suggestion_id
in: path
required: true
schema:
type: integer
responses:
'200':
description: Success
'403':
description: Missing or wrong X-Admin-Key, or ADMIN_API_KEY is not configured. Both are 403.
security:
- AdminAuth: []
description: Legacy human web app — moderation status update.
/api/bars/{slug}:
get:
operationId: getBarsSlug
summary: bars
tags:
- Public API
parameters:
- name: slug
in: path
required: true
schema:
type: integer
responses:
'200':
description: Success
description: Legacy human web app — bar detail by slug (legacy finder).
security: []
/api/cocktails/test:
get:
operationId: getCocktailsTest
summary: test
tags:
- Public API
parameters: []
responses:
'200':
description: Success
description: Legacy human web app — cocktail pipeline self-test.
security: []
/api/contact:
post:
operationId: postContact
summary: contact
tags:
- Public API
parameters: []
responses:
'200':
description: Success
description: Legacy human web app — contact form intake.
security: []
/api/focus-groups:
post:
operationId: postFocusGroups
summary: focus groups
tags:
- Public API
parameters: []
responses:
'410':
description: Gone. New focus-group and Brand Bar campaigns are not accepted.
description: Retired 2026-10-27. HTTP 410. Does not create a campaign or a Stripe Checkout session.
security: []
deprecated: true
/api/focus-groups/packages:
get:
operationId: getFocusGroupsPackages
summary: packages
tags:
- Public API
parameters: []
responses:
'200':
description: Success
description: Legacy human web app — focus-group package catalog.
security: []
deprecated: true
/api/focus-groups/{campaign_id}:
get:
operationId: getFocusGroupsCampaignId
summary: focus groups
tags:
- Public API
parameters:
- name: campaign_id
in: path
required: true
schema:
type: integer
responses:
'200':
description: Success
description: Legacy human web app — focus-group campaign detail.
security: []
deprecated: true
/api/geocode:
get:
operationId: getGeocode
summary: geocode
tags:
- Public API
parameters: []
responses:
'200':
description: Geocode result. Success includes searched_location_id and searched_location_token.
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
query:
type: string
lat:
type: number
lng:
type: number
formatted_address:
type: string
place_id:
type:
- string
- 'null'
address_components:
type: array
items:
type: object
searched_location_id:
type:
- integer
- 'null'
searched_location_token:
type:
- string
- 'null'
description: Owner token for PUT /api/searched-locations/{id}/bars-found. Header X-Searched-Location-Token. Null when SECRET_KEY is unset.
error:
type: string
description: Legacy human web app — address geocoding for the finder UI. On success the response includes searched_location_id and searched_location_token. Send the token as X-Searched-Location-Token on PUT /api/searched-locations/{id}/bars-found. searched_location_token is null when SECRET_KEY is unset (fail closed).
security: []
/api/geocode/autocomplete:
get:
operationId: getGeocodeAutocomplete
summary: autocomplete
tags:
- Public API
parameters: []
responses:
'200':
description: Success
description: Legacy human web app — address autocomplete for the finder UI.
security: []
/api/gift-certificates:
get:
operationId: getGiftCertificates
summary: gift certificates
tags:
- Public API
parameters: []
responses:
'200':
description: Success
description: Legacy human web app — gift certificate catalog.
security: []
deprecated: true
/api/gift-certificates/purchase:
post:
operationId: postGiftCertificatesPurchase
summary: purchase
tags:
- Public API
parameters: []
responses:
'200':
description: Success
description: Legacy human web app — gift certificate purchase checkout.
security: []
deprecated: true
/api/gift-certificates/redeem:
post:
operationId: postGiftCertificatesRedeem
summary: redeem
tags:
- Public API
parameters: []
responses:
'200':
description: Success
'401':
description: Invalid agent credentials
security:
- AgentAuth: []
description: Accepts agent token auth (X-Agent-ID/X-Agent-Token); primary caller is the legacy human web app.
deprecated: true
/api/gift-certificates/{code}:
get:
operationId: getGiftCertificatesCode
summary: gift certificates
tags:
- Public API
parameters:
- name: code
in: path
required: true
schema:
type: integer
responses:
'200':
description: Success
description: Legacy human web app — gift certificate lookup.
security: []
deprecated: true
/api/health:
get:
operationId: getHealth
summary: health
tags:
- Public API
parameters: []
responses:
'200':
description: Success
description: Liveness/readiness probe consumed by uptime monitors and the CD pipeline; publishing it invites synthetic-traffic noise.
security: []
/api/payments/base/stats:
get:
operationId: getPaymentsBaseStats
summary: stats
tags:
- Public API
parameters: []
responses:
'200':
description: Success
description: Legacy base-payments surface — internal stats.
security: []
/api/payments/base/verify:
post:
operationId: postPaymentsBaseVerify
summary: verify
tags:
- Public API
parameters: []
responses:
'200':
description: Success
'401':
description: Invalid agent credentials
security:
- AgentAuth: []
description: Legacy base-payments surface — payment verification.
/api/payments/base/webhook:
post:
operationId: postPaymentsBaseWebhook
summary: webhook
tags:
- Public API
parameters: []
responses:
'200':
description: Signature valid. processed=true when a pending Base USDC transfer was confirmed. processed=false is definitive (wrong amount, recipient, or token; receipt status 0; replayed tx_hash; zero amount; no matching pending row; removed/reorg activity; or the row was no longer pending). Do not retry a processed=false delivery.
'400':
description: Body is not a JSON object, or the delivery contains more than 20 activities. Nothing is confirmed. Do not retry the same body.
'401':
description: Missing, non-hex, or invalid X-Alchemy-Signature. Nothing is confirmed. Do not retry the same bytes.
'413':
description: Body exceeds the 256 KB webhook limit (Content-Length or the bytes actually read). Nothing is confirmed.
'502':
description: Base JSON-RPC failed (timeout, non-200, or a JSON-RPC error) while reading the receipt or the chain head. Nothing was confirmed. Retry; the provider should redeliver.
'503':
description: Retryable. Signing key unset, or Base treasury / USDC contract unset (Webhook verification unavailable), or the receipt is not available yet, or the block is not yet X402_MIN_CONFIRMATIONS deep (Awaiting confirmations, default 2). Nothing was confirmed. Retry.
security:
- AlchemyWebhookSignature: []
description: Alchemy Notify webhook for incoming Base USDC transfers to the DrinkedIn treasury. Server-to-server only; clients must not call it. Requires X-Alchemy-Signature (hex HMAC-SHA256 of the raw body). Confirms a pending transfer only after the receipt is successful, the USDC Transfer matches the payer, treasury, and amount, the tx_hash is not already used on real_usdc_transactions or x402_payment_requests (case-insensitive), and the block is at least X402_MIN_CONFIRMATIONS deep (default 2). A removed activity is a reorg and is not confirmed. A missing receipt or a shallow block is 503 so the provider redelivers; a definitive mismatch is 200 processed=false and must not be retried.
/api/searched-locations/{location_id}/bars-found:
put:
operationId: putSearchedLocationsLocationIdBarsFound
summary: Update bars-found count for a searched location
tags:
- Public API
parameters:
- name: location_id
in: path
required: true
schema:
type: integer
responses:
'200':
description: Updated. bars_found is the server count for owner tokens, or the explicit count for admin.
'400':
description: Admin sent a negative or non-integer bars_found, or the location has no coordinates so a non-admin count cannot be computed. Nothing is written.
'403':
description: Missing, invalid, expired, or wrong-id owner token, and no matching X-Admin-Key. Nothing is written. A nonexistent id without a valid credential is 403, not 404.
'404':
description: Authenticated, but no SearchedLocation with this id.
'500':
description: Failed to update bars_found. Generic message; exception text is not returned.
description: 'Finder flow bookkeeping. Requires X-Searched-Location-Token (owner proof issued by GET /api/geocode, max age 1 hour) or X-Admin-Key. Missing, invalid, expired, or wrong-id credentials are 403 and write nothing. A nonexistent id with no credential is 403, not 404. Non-admin callers do not set the count: the server counts nearby bars from the stored coordinates (same query as GET /api/bars/nearby, radius 10 km, limit 50). Admin callers may send an explicit bars_found. Fewer than 10 bars re-queues the location for the nightly scraper.'
security:
- SearchedLocationToken: []
- AdminAuth: []
requestBody:
content:
application/json:
schema:
type: object
properties:
bars_found:
type: integer
minimum: 0
description: Honoured only for X-Admin-Key callers. Ignored for owner-token callers; the server computes the count.
/api/sponsorships/bars/{sponsorship_id}:
get:
operationId: getSponsorshipsBarsSponsorshipId
summary: bars
tags:
- Public API
parameters:
- name: sponsorship_id
in: path
required: true
schema:
type: integer
responses:
'200':
description: Success
description: X-Admin-Token gated — sponsorship detail.
security:
- AdminAuth: []
deprecated: true
/api/sponsorships/brands/create-checkout-session:
post:
operationId: postSponsorshipsBrandsCreateCheckoutSession
summary: create checkout session
tags:
- Public API
parameters: []
responses:
'200':
description: Success
description: Public self-serve Stripe Checkout for brand sponsorship. Creates a Checkout session only; nothing is written to the DB. The grant happens on the Stripe-signature-verified webhook after payment.
security: []
deprecated: true
components:
securitySchemes:
AgentAuth:
type: apiKey
in: header
name: X-Agent-ID
description: Agent authentication using X-Agent-ID and X-Agent-Token headers
scopes:
agent_id: Agent ID for authentication
agent_token: Agent token for authentication
ApiKeyAuth:
type: apiKey
in: header
name: X-API-Key
description: Data-product licence key. Issued by POST /api/data/v1/licenses/subscribe/{stripe,x402}. One licence covers one product.
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: Human user session token from POST /api/auth/login (flask-jwt-extended).
AdminAuth:
type: apiKey
in: header
name: X-Admin-Key
description: Platform admin key. Must match ADMIN_API_KEY. Fail closed when that variable is unset or empty. Sponsorship admin routes also accept the same secret in X-Admin-Token (ADMIN_API_TOKEN is a legacy alias; ADMIN_API_KEY wins when both are set).
SearchedLocationToken:
type: apiKey
in: header
name: X-Searched-Location-Token
description: 'Owner proof for PUT /api/searched-locations/{location_id}/bars-found. Issued as searched_location_token on GET /api/geocode (itsdangerous URLSafeTimedSerializer, app SECRET_KEY, salt searched-location-bars-found-v1, max age 1 hour). Must match the path location_id. Fail closed: no token is issued when SECRET_KEY is unset. Alternative: AdminAuth (X-Admin-Key).'
AlchemyWebhookSignature:
type: apiKey
in: header
name: X-Alchemy-Signature
description: Hex HMAC-SHA256 of the raw request body, keyed with ALCHEMY_WEBHOOK_SIGNING_KEY (Alchemy Notify webhook signing key).
StripeSignature:
type: apiKey
in: header
name: Stripe-Signature
description: Stripe webhook signature. POST /api/sponsorships/webhook and POST /api/ai/agents/stripe/webhook reject a request with no Stripe-Signature, or a signature that does not match the endpoint secret. Not an agent credential.