OpenAPI Specification
openapi: 3.0.3
info:
title: Flynet App Locations API
version: '1.0'
description: 'Flynet''s partner API. Read access to member context, restaurants,
locations, check-ins, and memberships; write access for payment
intents.
**Base URL:** staging `https://api.staging.blackbird.xyz/flynet/v1`.
**Auth:** Two schemes — OAuth bearer (`Authorization: Bearer ...`) for
member-scoped routes, API key (`X-API-Key`) for restaurant and
location discovery. See Concepts → Authentication.
**Pagination:** `page` is zero-indexed (default `0`); `page_size`
default `50`. List responses include a `pagination` wrapper except
`GET /locations/{id}/open_hours`.
**Errors:** see Concepts → Pagination + errors. Three envelope shapes
are documented there.
'
servers:
- url: https://api.staging.blackbird.xyz/flynet/v1
description: Staging
security:
- oauthBearer: []
tags:
- name: Locations
description: Physical venues and open hours.
paths:
/locations:
get:
tags:
- Locations
summary: List locations
operationId: listLocations
description: Paginated list of locations.
security:
- apiKey: []
parameters:
- $ref: '#/components/parameters/Page'
- $ref: '#/components/parameters/PageSize'
responses:
'200':
description: Paginated locations.
content:
application/json:
schema:
$ref: '#/components/schemas/LocationList'
'401':
$ref: '#/components/responses/MissingApiKey'
/locations/{id}:
get:
tags:
- Locations
summary: Get a location
operationId: getLocation
description: Single location by UUID. Embeds parent restaurant and neighborhood.
security:
- apiKey: []
parameters:
- $ref: '#/components/parameters/LocationId'
responses:
'200':
description: Location found.
content:
application/json:
schema:
$ref: '#/components/schemas/Location'
'401':
$ref: '#/components/responses/MissingApiKey'
'404':
$ref: '#/components/responses/NotFound'
/locations/{id}/open_hours:
get:
tags:
- Locations
summary: List a location's open hours
operationId: listLocationOpenHours
description: 'Weekly open hours for a location. Not paginated — always returns
the full set, with missing days implying the location is closed.
'
security:
- apiKey: []
parameters:
- $ref: '#/components/parameters/LocationId'
responses:
'200':
description: Open hours for the location.
content:
application/json:
schema:
$ref: '#/components/schemas/OpenHoursList'
'401':
$ref: '#/components/responses/MissingApiKey'
'404':
$ref: '#/components/responses/NotFound'
components:
responses:
MissingApiKey:
description: 'Unauthorized. A **missing** `X-API-Key` returns an empty body with a `WWW-Authenticate: Bearer` header (read the header, not the body). An **invalid or revoked** key returns the JSON body below with `code: "invalid_api_key"`.
'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error:
type: authentication_error
code: invalid_api_key
message: Invalid or revoked API key.
param: null
NotFound:
description: The requested resource was not found.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
schemas:
Location:
type: object
required:
- id
- object
- restaurant
- neighborhood
- address
- time_zone
- payments_enabled
- is_club
- reservations_enabled
- created_at
- updated_at
properties:
id:
type: string
format: uuid
object:
type: string
enum:
- location
name:
type: string
nullable: true
restaurant:
$ref: '#/components/schemas/Restaurant'
neighborhood:
$ref: '#/components/schemas/Neighborhood'
slug:
type: string
address:
$ref: '#/components/schemas/Address'
coordinate:
allOf:
- $ref: '#/components/schemas/Coordinate'
nullable: true
phone_number:
type: string
nullable: true
time_zone:
type: string
payments_enabled:
type: boolean
is_club:
type: boolean
reservations_enabled:
type: boolean
reservation_url:
type: string
format: uri
nullable: true
google_place_id:
type: string
nullable: true
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
OpenHour:
type: object
required:
- object
- day_of_week
- open_time
- close_time
properties:
object:
type: string
enum:
- open_hour
day_of_week:
type: string
enum:
- monday
- tuesday
- wednesday
- thursday
- friday
- saturday
- sunday
open_time:
type: string
close_time:
type: string
Address:
type: object
properties:
street:
type: string
street2:
type: string
nullable: true
city:
type: string
state:
type: string
zipcode:
type: string
country:
type: string
Neighborhood:
type: object
properties:
id:
type: string
format: uuid
object:
type: string
enum:
- neighborhood
name:
type: string
region:
type: string
Coordinate:
type: object
properties:
latitude:
type: number
format: double
longitude:
type: number
format: double
OpenHoursList:
type: object
required:
- open_hours
properties:
open_hours:
type: array
items:
$ref: '#/components/schemas/OpenHour'
Restaurant:
type: object
required:
- id
- object
- name
- cuisine
- cohort
- tags
- created_at
- updated_at
properties:
id:
type: string
format: uuid
object:
type: string
enum:
- restaurant
name:
type: string
cuisine:
type: array
items:
type: string
cohort:
type: string
nullable: true
price:
type: integer
nullable: true
tags:
type: array
items:
type: object
additionalProperties: true
asset:
type: object
nullable: true
required:
- preview_1x
- web_2x
- full_3x
properties:
preview_1x:
type: string
format: uri
nullable: true
web_2x:
type: string
format: uri
nullable: true
full_3x:
type: string
format: uri
nullable: true
website_url:
type: string
format: uri
nullable: true
instagram_url:
type: string
format: uri
nullable: true
created_at:
type: string
format: date-time
updated_at:
type: string
format: date-time
Error:
type: object
required:
- error
properties:
error:
type: object
required:
- type
- code
- message
properties:
type:
type: string
code:
type: string
message:
type: string
param:
type: string
nullable: true
Pagination:
type: object
required:
- total_count
- total_pages
- current_page
- next_page
- page_size
properties:
total_count:
type: integer
total_pages:
type: integer
current_page:
type: integer
next_page:
type: integer
nullable: true
page_size:
type: integer
LocationList:
type: object
required:
- locations
- pagination
properties:
locations:
type: array
items:
$ref: '#/components/schemas/Location'
pagination:
$ref: '#/components/schemas/Pagination'
parameters:
PageSize:
name: page_size
in: query
schema:
type: integer
default: 50
description: Items per page. Default `50`.
Page:
name: page
in: query
schema:
type: integer
default: 0
minimum: 0
description: Zero-indexed page number.
LocationId:
name: id
in: path
required: true
schema:
type: string
format: uuid
example: c54a3b6a-c31b-49b4-8af1-2dfb70ff3eec
securitySchemes:
oauthBearer:
type: http
scheme: bearer
bearerFormat: JWT
description: 'OAuth 2.0 access token. Required for the `/users/me/*` routes
(profile, status, wallets, tags, check-ins, memberships) and all
payment intent routes.
'
apiKey:
type: apiKey
in: header
name: X-API-Key
description: 'Server-to-server API key prefixed `fly_live_...` (production) or
`fly_test_...` (staging/dev). Required on restaurant and location
Discovery routes and on the `/check_ins` venue feed (key minted
with `read:checkins`).
'