--- openapi: 3.0.1 info: title: API V1 version: v1 paths: "/api/v1/blocks": get: summary: Retrieve the account blocklist tags: - account security: - oauth: - account:read responses: '200': description: blocked accounts headers: Link: "$ref": "#/components/headers/PaginationLink" content: application/json: schema: type: array items: "$ref": "#/components/schemas/account_output" "/api/v1/accounts/{account_id}/block": post: summary: Block an account tags: - account security: - oauth: - account:write parameters: - name: account_id in: path required: true schema: type: integer responses: '201': description: block delete: summary: Unblock an account tags: - account security: - oauth: - account:write parameters: - name: account_id in: path required: true schema: type: integer responses: '204': description: unblock "/api/v1/accounts/{account_id}/followers": get: summary: Retrieve the account followers tags: - account security: - oauth: - account:read parameters: - name: account_id in: path required: true schema: type: integer responses: '200': description: followers headers: Link: "$ref": "#/components/headers/PaginationLink" content: application/json: schema: type: array items: "$ref": "#/components/schemas/account_output" "/api/v1/accounts/{account_id}/following": get: summary: Retrieve the accounts following this one tags: - account security: - oauth: - account:read parameters: - name: account_id in: path required: true schema: type: integer responses: '200': description: following headers: Link: "$ref": "#/components/headers/PaginationLink" content: application/json: schema: type: array items: "$ref": "#/components/schemas/account_output" "/api/v1/accounts/{account_id}/follow": post: summary: Follow an account tags: - account security: - oauth: - account:write parameters: - name: account_id in: path required: true schema: type: integer responses: '201': description: follow delete: summary: Unfollow an account tags: - account security: - oauth: - account:write parameters: - name: account_id in: path required: true schema: type: integer responses: '204': description: unfollow "/api/v1/accounts/{account_id}/recipes/{slug}": get: summary: Retrieve the required recipe tags: - recipe parameters: - name: account_id in: path required: true schema: type: integer - name: slug in: path required: true schema: type: string responses: '200': description: recipe content: application/json: schema: "$ref": "#/components/schemas/recipe_output" "/api/v1/accounts/relationships": get: summary: Retrieve the account relationships tags: - account security: - oauth: - account:read parameters: - name: id in: query schema: type: array items: type: number style: form explode: true responses: '200': description: relationships content: application/json: schema: type: array items: type: object additionalProperties: false properties: id: type: number following: type: boolean followed: type: boolean following_requested: type: boolean follower_requested: type: boolean blocking: type: boolean required: - id - following - followed - following_requested - follower_requested - blocking "/api/v1/accounts/{account_id}/timeline": get: summary: Retrieve the account's timeline tags: - timeline - recipe - baking - status parameters: - name: account_id in: path required: true schema: type: integer - name: with_replies in: query description: When true, includes reply events in the timeline in addition to original posts. Defaults to false. schema: type: boolean responses: '200': description: events list headers: Link: "$ref": "#/components/headers/PaginationLink" content: application/json: schema: type: array items: "$ref": "#/components/schemas/event_output" "/api/v1/accounts/{id_or_username}": get: summary: Retrieve the requested account tags: - account security: [] parameters: - name: id_or_username in: path required: true schema: type: string responses: '200': description: account available content: application/json: schema: "$ref": "#/components/schemas/account_output" "/api/v1/applications": post: summary: Create a new application tags: - application parameters: [] responses: '201': description: app created content: application/json: schema: type: object additionalProperties: false properties: client_id: type: string client_secret: type: string client_secret_expires_at: type: integer '422': description: invalid request content: application/json: schema: "$ref": "#/components/schemas/errors" requestBody: content: application/json: schema: type: object additionalProperties: false properties: application: "$ref": "#/components/schemas/application_input" required: - application "/api/v1/bakings/{id}/publish": post: summary: Publish a baking tags: - baking security: - oauth: - write parameters: - name: id in: path required: true schema: type: integer responses: '204': description: baking published requestBody: content: application/json: schema: type: object additionalProperties: false properties: baking: type: object additionalProperties: false properties: visibility: type: string enum: - public - unlisted - followers - private delete: summary: Unpublish a baking tags: - baking security: - oauth: - write parameters: - name: id in: path required: true schema: type: integer responses: '204': description: baking deleted "/api/v1/bakings": get: summary: Retrieve all of the user's bakings tags: - baking security: - oauth: - read parameters: - name: start_date in: query schema: type: string format: date - name: end_date in: query schema: type: string format: date - name: status in: query schema: type: string responses: '200': description: bakings list headers: Link: "$ref": "#/components/headers/PaginationLink" content: application/json: schema: type: array items: "$ref": "#/components/schemas/baking_output" post: summary: Create a new baking tags: - baking security: - oauth: - write parameters: [] responses: '201': description: baking created content: application/json: schema: "$ref": "#/components/schemas/baking_output" '422': description: invalid request content: application/json: schema: "$ref": "#/components/schemas/errors" requestBody: content: application/json: schema: type: object additionalProperties: false properties: baking: "$ref": "#/components/schemas/baking_create_input" "/api/v1/bakings/{id}": get: summary: Retrieve the specified baking by its id tags: - baking security: [] parameters: - name: id in: path required: true schema: type: integer responses: '200': description: single baking content: application/json: schema: "$ref": "#/components/schemas/baking_output" patch: summary: Update an existing baking tags: - baking security: - oauth: - write parameters: - name: id in: path required: true schema: type: integer responses: '204': description: baking updated '422': description: invalid request content: application/json: schema: "$ref": "#/components/schemas/errors" requestBody: content: application/json: schema: type: object additionalProperties: false properties: baking: "$ref": "#/components/schemas/baking_input" delete: summary: Delete a baking tags: - baking security: - oauth: - write parameters: - name: id in: path required: true schema: type: integer responses: '204': description: baking deleted "/api/v1/collections/{id}/items": get: summary: Retrieve the specified collection's items tags: - collection - recipe - baking - status security: - oauth: - read parameters: - name: id in: path required: true schema: type: integer responses: '200': description: collection items content: application/json: schema: type: array items: "$ref": "#/components/schemas/collection_item_output" "/api/v1/collections/{collection_id}/items/{id}": post: summary: Append a record to the collection tags: - collection - recipe - baking - status security: - oauth: - write parameters: - name: collection_id in: path required: true schema: type: integer - name: id in: path required: true schema: type: integer - name: type in: query required: true schema: type: string responses: '201': description: record appended delete: summary: Remove a record from the collection tags: - collection - recipe - baking - status security: - oauth: - write parameters: - name: collection_id in: path required: true schema: type: integer - name: id in: path required: true schema: type: integer - name: type in: query required: true schema: type: string responses: '204': description: record removed "/api/v1/collections": get: summary: Retrieve all of the user's collections tags: - collection security: - oauth: - read responses: '200': description: collections list headers: Link: "$ref": "#/components/headers/PaginationLink" content: application/json: schema: type: array items: "$ref": "#/components/schemas/collection_output" post: summary: Create a new collection tags: - collection security: - oauth: - write parameters: [] responses: '201': description: collection created content: application/json: schema: "$ref": "#/components/schemas/collection_output" '422': description: invalid request content: application/json: schema: "$ref": "#/components/schemas/errors" requestBody: content: application/json: schema: type: object additionalProperties: false properties: collection: "$ref": "#/components/schemas/collection_input" "/api/v1/collections/{id}": get: summary: Retrieve the specified collection by its id tags: - collection security: - oauth: - read parameters: - name: id in: path required: true schema: type: integer responses: '200': description: single collection content: application/json: schema: "$ref": "#/components/schemas/collection_output" patch: summary: Update an existing collection tags: - collection security: - oauth: - write parameters: - name: id in: path required: true schema: type: integer responses: '204': description: collection updated '422': description: invalid request content: application/json: schema: "$ref": "#/components/schemas/errors" requestBody: content: application/json: schema: type: object additionalProperties: false properties: collection: "$ref": "#/components/schemas/collection_input" delete: summary: Delete a collection tags: - collection security: - oauth: - write parameters: - name: id in: path required: true schema: type: integer responses: '204': description: collection deleted "/api/v1/recipes/{id}/boost": post: summary: Boost a recipe tags: - recipe security: - oauth: - write parameters: - name: id in: path required: true schema: type: integer responses: '204': description: recipe boosted delete: summary: Unboost a recipe tags: - recipe security: - oauth: - write parameters: - name: id in: path required: true schema: type: integer responses: '204': description: recipe unboosted "/api/v1/bakings/{id}/boost": post: summary: Boost a baking tags: - baking security: - oauth: - write parameters: - name: id in: path required: true schema: type: integer responses: '204': description: baking boosted delete: summary: Unboost a baking tags: - baking security: - oauth: - write parameters: - name: id in: path required: true schema: type: integer responses: '204': description: baking unboosted "/api/v1/statuses/{id}/boost": post: summary: Boost a status tags: - status security: - oauth: - write parameters: - name: id in: path required: true schema: type: integer responses: '204': description: status boosted delete: summary: Unboost a status tags: - status security: - oauth: - write parameters: - name: id in: path required: true schema: type: integer responses: '204': description: status unboosted "/api/v1/bakings/{eventable_id}/media": parameters: - name: eventable_id in: path required: true schema: type: integer post: summary: Create a new media for a baking tags: - baking security: - oauth: - write parameters: [] responses: '201': description: media created content: application/json: schema: "$ref": "#/components/schemas/medium_output" '422': description: invalid request content: application/json: schema: "$ref": "#/components/schemas/errors" requestBody: content: multipart/form-data: schema: type: object additionalProperties: false properties: media: "$ref": "#/components/schemas/medium_input" "/api/v1/bakings/{eventable_id}/media/{id}": parameters: - name: eventable_id in: path required: true schema: type: integer patch: summary: Update a media for a baking tags: - baking security: - oauth: - write parameters: - name: id in: path required: true schema: type: integer responses: '204': description: media updated requestBody: content: application/json: schema: type: object additionalProperties: false properties: media: type: object additionalProperties: false properties: description: type: string delete: summary: Delete a media for a baking tags: - baking security: - oauth: - write parameters: - name: id in: path required: true schema: type: integer responses: '204': description: media deleted "/api/v1/statuses/{eventable_id}/media": parameters: - name: eventable_id in: path required: true schema: type: integer post: summary: Create a new media for a status tags: - status security: - oauth: - write parameters: [] responses: '201': description: media created content: application/json: schema: "$ref": "#/components/schemas/medium_output" '422': description: invalid request content: application/json: schema: "$ref": "#/components/schemas/errors" requestBody: content: multipart/form-data: schema: type: object additionalProperties: false properties: media: "$ref": "#/components/schemas/medium_input" "/api/v1/statuses/{eventable_id}/media/{id}": parameters: - name: eventable_id in: path required: true schema: type: integer patch: summary: Update a media for a status tags: - status security: - oauth: - write parameters: - name: id in: path required: true schema: type: integer responses: '204': description: media updated requestBody: content: application/json: schema: type: object additionalProperties: false properties: media: type: object additionalProperties: false properties: description: type: string delete: summary: Delete a media for a status tags: - status security: - oauth: - write parameters: - name: id in: path required: true schema: type: integer responses: '204': description: media deleted "/api/v1/recipes/{recipe_id}/media": get: summary: Retrieve the recipe's media available to the current user tags: - recipe parameters: - name: recipe_id in: path required: true schema: type: integer responses: '200': description: media content: application/json: schema: type: array items: "$ref": "#/components/schemas/extended_medium_output" "/api/v1/recipes": get: summary: Retrieve all of the user's recipes tags: - recipe security: - oauth: - read responses: '200': description: recipes list headers: Link: "$ref": "#/components/headers/PaginationLink" content: application/json: schema: type: array items: "$ref": "#/components/schemas/recipe_output" post: summary: Create a new recipe tags: - recipe security: - oauth: - write parameters: [] responses: '201': description: recipe created content: application/json: schema: "$ref": "#/components/schemas/recipe_output" '422': description: invalid request content: application/json: schema: "$ref": "#/components/schemas/errors" requestBody: content: application/json: schema: type: object additionalProperties: false properties: recipe: "$ref": "#/components/schemas/recipe_create_input" "/api/v1/recipes/{id}": get: summary: Retrieve the specified recipe by its id tags: - recipe security: [] parameters: - name: id in: path required: true schema: type: integer responses: '200': description: single recipe content: application/json: schema: "$ref": "#/components/schemas/recipe_output" patch: summary: Update an existing recipe tags: - recipe security: - oauth: - write parameters: - name: id in: path required: true schema: type: integer responses: '204': description: recipe updated '422': description: invalid request content: application/json: schema: "$ref": "#/components/schemas/errors" requestBody: content: application/json: schema: type: object additionalProperties: false properties: recipe: "$ref": "#/components/schemas/recipe_input" delete: summary: Delete a recipe tags: - recipe security: - oauth: - write parameters: - name: id in: path required: true schema: type: integer responses: '204': description: recipe deleted "/api/v1/recipes/{recipe_id}/links": get: summary: Recursively retrieve the specified recipe's linked recipes tags: - recipe security: [] parameters: - name: recipe_id in: path required: true schema: type: integer responses: '200': description: links headers: Link: "$ref": "#/components/headers/PaginationLink" content: application/json: schema: type: array items: "$ref": "#/components/schemas/recipe_output" "/api/v1/search": get: summary: Perform a search tags: - search security: - oauth: - read parameters: - name: query in: query schema: type: string - name: type in: query schema: type: string responses: '200': description: search query headers: Link: "$ref": "#/components/headers/PaginationLink" content: application/json: schema: type: array items: type: object additionalProperties: false properties: type: type: string enum: - recipe - baking data: type: object anyOf: - "$ref": "#/components/schemas/recipe_output" - "$ref": "#/components/schemas/baking_output" required: - type - data "/api/v1/statuses/{id}": get: summary: Retrieve the specified status by its id tags: - status security: [] parameters: - name: id in: path required: true schema: type: integer responses: '200': description: single status content: application/json: schema: "$ref": "#/components/schemas/status_output" "/api/v1/timeline": get: summary: Retrieve the timeline for the current account tags: - timeline - recipe - baking - status security: - oauth: - read parameters: - name: min_id in: query required: false description: Cursor for forward pagination. Returns entries with an ID immediately greater than this value, starting from that position. Use this to page forward through older-to-newer content from a known position. schema: type: integer - name: max_id in: query required: false description: Upper bound for backward pagination. Returns only entries with an ID less than this value, ordered newest first. Use this to load older content beyond the current page. schema: type: integer - name: order in: query required: false description: Sort order for results. When set to `asc`, entries are returned oldest first (useful with `min_id` for forward pagination). When set to `desc`, entries are returned newest first. Defaults to `desc` when omitted. schema: type: string enum: - asc - desc responses: '200': description: events list content: application/json: schema: type: array items: "$ref": "#/components/schemas/event_output" "/api/v1/user": get: summary: Retrieve the user tags: - user security: - oauth: - account:read responses: '200': description: user available content: application/json: schema: "$ref": "#/components/schemas/user_output" '401': description: unauthorized security: - oauth: [] components: securitySchemes: oauth: type: oauth2 flows: authorizationCode: authorizationUrl: "/oauth/authorize" tokenUrl: "/oauth/token" scopes: all: Full read and write access to your account and all its data. read: Read access to all your data. write: Create, update, and delete content on your behalf. account:read: Read your profile information. account:write: Update your profile information. headers: PaginationLink: description: | Pagination links following RFC 5988 (Web Linking). The `Link` header may contain one or more relations: - `rel="next"` — URL of the next page - `rel="prev"` — URL of the previous page - `rel="first"` — URL of the first page - `rel="last"` — URL of the last page Example: ; rel="next", ; rel="first" schema: type: string nullable: true example: ; rel="next", ; rel="first" schemas: account_output: type: object additionalProperties: false properties: id: type: integer username: type: string name: type: string summary: type: string summary_html: type: string instance: type: string avatar: type: object properties: original: type: string small: type: string medium: type: string required: - original - small - medium state: type: string enum: - unknown - loading - loaded description: | The account's current sync status. - `unknown`: We don't know anything about this account. It may not even exist. - `loading`: We have loaded this account's direct information, and are currently loading the statuses. - `loaded`: We have loaded the data from this account. Note that this doesn't mean we actually have 100% of the data. There could be new data we haven't loaded yet, or that wasn't delivered to us. Local and managed accounts always have a state of `loaded`. following_count: type: integer followers_count: type: integer like_id: type: integer required: - id - username - name - summary - summary_html - instance - avatar - state - following_count - followers_count - like_id user_output: type: object additionalProperties: false properties: id: type: integer admin: type: boolean locale: type: string account: "$ref": "#/components/schemas/account_output" required: - id - admin - account - locale recipe_input: type: object properties: name: type: string description: type: string serving: type: integer serving_type: type: string visibility: type: string enum: - public - unlisted - followers - private ingredients: type: array items: type: object additionalProperties: false properties: id: type: integer position: type: integer name: type: string quantity: type: number unit: type: string enum: - '' - mg - g - kg - ml - cl - l - pinch - tablespoon - teaspoon - sachet - slice required: - position - name - quantity - unit steps: type: array items: anyOf: - "$ref": "#/components/schemas/recipe_step_content_input" - "$ref": "#/components/schemas/recipe_step_link_input" - "$ref": "#/components/schemas/recipe_step_wait_input" recipe_create_input: allOf: - "$ref": "#/components/schemas/recipe_input" - required: - name - description - serving - serving_type - visibility - ingredients - steps recipe_output: type: object additionalProperties: false properties: id: type: integer slug: type: string name: type: string description: type: string description_html: type: string locale: type: string enum: - en - fr nullable: true serving: type: integer serving_type: type: string visibility: type: string enum: - public - unlisted - followers - private account: "$ref": "#/components/schemas/account_output" likes_count: type: integer boosts_count: type: integer liked: type: boolean boosted: type: boolean ingredients: type: array items: type: object additionalProperties: false properties: id: type: integer position: type: integer name: type: string quantity: type: number unit: type: string enum: - '' - mg - g - kg - ml - cl - l - pinch - tablespoon - teaspoon - sachet - slice required: - id - position - name - quantity - unit steps: type: array items: anyOf: - "$ref": "#/components/schemas/recipe_step_content_output" - "$ref": "#/components/schemas/recipe_step_link_output" - "$ref": "#/components/schemas/recipe_step_wait_output" required: - id - slug - name - visibility - description - description_html - locale - serving - serving_type - account - likes_count - boosts_count - liked - boosted - ingredients - steps recipe_step_content_input: type: object properties: id: type: integer position: type: integer type: type: string enum: - content content: type: string required: - position - type - content recipe_step_link_input: type: object properties: id: type: integer position: type: integer type: type: string enum: - link serving: type: integer link_id: type: integer nullable: true required: - position - type - serving - link_id recipe_step_wait_input: type: object properties: id: type: integer position: type: integer type: type: string enum: - wait content: type: string duration: type: integer required: - position - type - content - duration recipe_step_content_output: type: object additionalProperties: false properties: id: type: integer position: type: integer type: type: string enum: - content content: type: string content_html: type: string required: - id - position - type - content - content_html recipe_step_link_output: type: object additionalProperties: false properties: id: type: integer position: type: integer type: type: string enum: - link link_id: type: integer serving: type: integer required: - id - position - type - link_id - serving recipe_step_wait_output: type: object additionalProperties: false properties: id: type: integer position: type: integer type: type: string enum: - wait content: type: string duration: type: integer required: - id - position - type - duration - content baking_input: type: object properties: name: type: string description: type: string status: type: string enum: - unmanaged - planning - shopping - preparing - eating - done serving: type: integer prepared_at: type: string recipe_id: type: integer baking_create_input: allOf: - "$ref": "#/components/schemas/baking_input" - required: - name - prepared_at baking_output: type: object additionalProperties: false properties: id: type: integer name: type: string description: type: string description_html: type: string status: type: string enum: - unmanaged - planning - shopping - preparing - eating - done serving: type: integer prepared_at: type: string recipe: "$ref": "#/components/schemas/recipe_output" nullable: true likes_count: type: integer boosts_count: type: integer liked: type: boolean boosted: type: boolean published_at: type: string nullable: true account: "$ref": "#/components/schemas/account_output" media: type: array items: "$ref": "#/components/schemas/medium_output" required: - id - account - published_at - likes_count - boosts_count - liked - boosted - name - description - description_html - status - serving - prepared_at - recipe - media medium_input: type: object properties: document: type: string format: binary description: type: string required: - document medium_output: type: object properties: id: type: integer description: type: string created_at: type: string original: type: string medium: type: string small: type: string required: - id - created_at - description - original - medium - small extended_medium_output: allOf: - "$ref": "#/components/schemas/medium_output" - type: object properties: account: "$ref": "#/components/schemas/account_output" required: - account status_output: type: object additionalProperties: false properties: id: type: integer content: type: string content_html: type: string locale: type: string likes_count: type: integer boosts_count: type: integer liked: type: boolean boosted: type: boolean account: "$ref": "#/components/schemas/account_output" media: type: array items: "$ref": "#/components/schemas/medium_output" required: - id - content - content_html - likes_count - boosts_count - liked - boosted - locale - account - media application_input: type: object properties: client_name: type: string scopes: type: string redirect_uris: type: array items: type: string required: - client_name - scopes - redirect_uris short_eventable_output: type: object anyOf: - type: object additionalProperties: false properties: id: type: integer slug: type: string account: "$ref": "#/components/schemas/account_output" name: type: string liked: type: boolean boosted: type: boolean likes_count: type: integer boosts_count: type: integer serving: type: number serving_type: type: string description: type: string description_html: type: string locale: type: string created_at: type: string required: - id - slug - account - name - liked - boosted - likes_count - boosts_count - serving - serving_type - description - description_html - locale - created_at - type: object additionalProperties: false properties: id: type: integer name: type: string description: type: string description_html: type: string account: "$ref": "#/components/schemas/account_output" liked: type: boolean boosted: type: boolean likes_count: type: integer boosts_count: type: integer status: type: string serving: type: number prepared_at: type: string created_at: type: string media: type: array items: "$ref": "#/components/schemas/medium_output" recipe: type: object additionalProperties: false nullable: true properties: id: type: integer slug: type: string name: type: string account: "$ref": "#/components/schemas/account_output" serving: type: number serving_type: type: string description: type: string description_html: type: string locale: type: string created_at: type: string required: - id - slug - name - account - serving - serving_type - description - description_html - locale - created_at required: - id - name - description - description_html - account - liked - boosted - likes_count - boosts_count - status - serving - prepared_at - created_at - media - recipe - type: object additionalProperties: false properties: id: type: integer account: "$ref": "#/components/schemas/account_output" liked: type: boolean boosted: type: boolean likes_count: type: integer boosts_count: type: integer content: type: string content_html: type: string media: type: array items: "$ref": "#/components/schemas/medium_output" locale: type: string created_at: type: string required: - id - account - liked - boosted - likes_count - boosts_count - content - content_html - media - locale - created_at event_output: type: object additionalProperties: false properties: id: type: integer format: int64 type: type: string enum: - recipe - baking - status action: type: string enum: - create - update - delete - announce created_at: type: string account: "$ref": "#/components/schemas/account_output" object: "$ref": "#/components/schemas/short_eventable_output" required: - id - type - action - created_at - account - object collection_input: type: object properties: name: type: string required: - name collection_output: type: object additionalProperties: false properties: id: type: integer name: type: string required: - id - name collection_item_output: type: object additionalProperties: false properties: id: type: integer type: type: string account: "$ref": "#/components/schemas/account_output" object: "$ref": "#/components/schemas/short_eventable_output" required: - id - type - account - object errors: type: object properties: errors: type: object additionalProperties: type: array items: type: string required: - errors servers: - url: "/"