Apiary API

openapi: 3.1.0
info:
  title: Apiary API
  version: '2020-03-02'
  summary: Apiary loves APIs. Of course then, we have an API too.
  description: >-
    The Apiary API is Apiary.io's own public API. This OpenAPI 3.1 document is a
    faithful, one-to-one translation of the API Blueprint / API Elements description
    that Apiary itself publishes and serves at
    https://jsapi.apiary.io/apis/apiary (rendered for humans at
    https://apiary.docs.apiary.io). Every path, method, parameter, status code,
    header, media type, example and schema below is taken verbatim from that
    document. Nothing has been invented, and no operation was added that Apiary
    does not describe.


    Three distinct authentication schemes are in play and they are NOT
    interchangeable — the Apiary API description is explicit about which one each
    resource takes:

    * `/authorization` accepts HTTP **Basic** authentication (account email +
      password) and is used to mint, list and revoke tokens. It does not work for
      users who are part of an IDCS-controlled (Oracle Identity Cloud Service) team.
    * `/me` and `/me/apis` and `/me/teams/{teamId}/apis` take an **RFC 6750 Bearer**
      token in the `Authorization` header.
    * `/blueprint/*` is described by Apiary as **legacy** and takes the older
      non-standard `Authentication: Token <token>` header, not `Authorization`.

    All requests must be made over TLS; a plaintext request is answered `403` with
    `{"error": "Transport Layer Security Required"}`.
  contact:
    name: Apiary Support
    email: support@apiary.io
    url: https://help.apiary.io
  license:
    name: Proprietary — Oracle Cloud Infrastructure
    url: https://apiary.io/tos
  termsOfService: https://apiary.io/tos
  x-apiary-description-format: apiblueprint
  x-apiary-last-updated: '2020-03-02T13:09:52.558Z'
  x-provenance:
    generated: '2026-09-02'
    method: derived
    source: https://jsapi.apiary.io/apis/apiary
    source_http_status: 200
    source_saved_verbatim: api-description/apiary-api-description.json
    note: >-
      Derived from Apiary's own published API description document, fetched from
      Apiary's own host (jsapi.apiary.io) and describing Apiary's own production
      host (https://api.apiary.io/). Ownership is unambiguous: the description
      names itself "Apiary API", is owned by the Apiary account, declares
      production base https://api.apiary.io/, and lists support@apiary.io. Apiary
      publishes no OpenAPI/Swagger of its own — /openapi.json, /openapi.yaml,
      /swagger.json, /api-docs, /docs and /redoc all return 404 on api.apiary.io
      (probed 2026-09-02) — so this document is a translation, not a harvest.
externalDocs:
  description: Apiary API interactive documentation (Apiary-hosted)
  url: https://apiary.docs.apiary.io
servers:
  - url: https://api.apiary.io
    description: Production
tags:
  - name: Authentication
    description: >-
      Apiary API uses Bearer Token Authorization (RFC 6750). Tokens are managed at
      https://login.apiary.io/tokens, or created, listed and deleted over this
      resource using Basic Authentication. This collection works only for users
      who are not part of IDCS-controlled teams.
    externalDocs:
      url: https://login.apiary.io/tokens
  - name: User Information
    description: Apiary API exposes authorized user information. You may only get your own user information.
  - name: API List
    description: >-
      Apiary API exposes lists of APIs. Your authorization token grants access to
      private and public, personal and team API Projects.
  - name: Blueprint
    description: >-
      Legacy API Blueprint utilities. These operations take the legacy
      `Authentication: Token <token>` header rather than `Authorization: Bearer`.
paths:
  /authorization:
    post:
      operationId: createAuthorizationToken
      summary: Create an Authorization Token
      description: >-
        Create a new authorization token for an authenticated user. This
        authorization token may be used to access protected resources. Pass
        `tokenRegenerate=true` to regenerate a token that already exists under the
        same description.
      tags: [Authentication]
      security:
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required: [tokenDescription]
              properties:
                tokenDescription:
                  type: string
                  maxLength: 30
                  description: A string, 30 characters or less, describing the token.
                tokenRegenerate:
                  type: boolean
                  default: false
                  description: Regenerate the token if one already exists with this description.
            example:
              tokenDescription: What's this token for?
              tokenRegenerate: false
      responses:
        '201':
          description: Token created (or regenerated).
          headers:
            Location:
              description: URL of the newly created token resource.
              schema:
                type: string
                format: uri
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Token'
        '400':
          description: >-
            Token Description Missing, Token Description Length Greater Than 30, or
            Token Description Already Exists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Transport Layer Security Required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    get:
      operationId: listAuthorizationTokens
      summary: Get Existing Authorization Tokens
      description: >-
        Get existing authorization tokens for an authenticated user. Token values
        themselves are not returned — only their descriptions and resource URLs.
      tags: [Authentication]
      security:
        - basicAuth: []
      responses:
        '200':
          description: The caller's token list.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TokenList'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Transport Layer Security Required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    delete:
      operationId: deleteAuthorizationToken
      summary: Delete an Existing Authorization Token
      description: >-
        Delete an existing authorization token for an authenticated user. The
        token may no longer be used to access protected resources. The token to
        delete is identified by its description, either form-encoded in the body or
        percent-encoded as a path segment on the token URL.
      tags: [Authentication]
      security:
        - basicAuth: []
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required: [tokenDescription]
              properties:
                tokenDescription:
                  type: string
                  maxLength: 30
                  description: The description identifying the token to delete.
            example:
              tokenDescription: What's this token for?
      responses:
        '204':
          description: Token deleted. No content.
        '400':
          description: Token Description Missing, or Token Description Length Greater Than 30.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Transport Layer Security Required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /me:
    get:
      operationId: getMe
      summary: Get Me
      description: >-
        Get your user information. A valid authorization token must be used to
        access this information. You may only get your own user information.
      tags: [User Information]
      security:
        - bearerAuth: []
      responses:
        '200':
          description: The authenticated user, with the teams they belong to.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/User'
        '401':
          description: Token Invalid.
          headers:
            WWW-Authenticate:
              description: 'Bearer error="invalid_token"'
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Transport Layer Security Required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /me/apis:
    get:
      operationId: listMyApis
      summary: Get User API List
      description: >-
        Get a list of public and private, personal and team APIs an authorized user
        may access.
      tags: [API List]
      security:
        - bearerAuth: []
      responses:
        '200':
          description: The API Projects the caller may access.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiList'
        '401':
          description: Token Invalid.
          headers:
            WWW-Authenticate:
              description: 'Bearer error="invalid_token"'
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Transport Layer Security Required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /me/teams/{teamId}/apis:
    parameters:
      - name: teamId
        in: path
        required: true
        description: A team ID.
        schema:
          type: string
        example: 518bcf09a6e4580200000...
    get:
      operationId: listTeamApis
      summary: Get Team API List
      description: Get a list of public and private, team APIs an authorized user may access.
      tags: [API List]
      security:
        - bearerAuth: []
      responses:
        '200':
          description: The team's API Projects.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiList'
        '401':
          description: Token Invalid.
          headers:
            WWW-Authenticate:
              description: 'Bearer error="invalid_token"'
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Transport Layer Security Required.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Team ID Invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /blueprint/create:
    post:
      operationId: createApiProject
      summary: Create API Project
      description: >-
        Create a new API Project from an API description document. If the
        `desiredName` is already taken, a different `domain` will be generated for
        your API Project; it can be changed later in the project settings.
      tags: [Blueprint]
      security:
        - legacyToken: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                type:
                  type: string
                  enum: [personal, team]
                  description: Whether the API Project is personal or belongs to a team.
                public:
                  type: boolean
                  description: Whether the API Project is publicly visible.
                desiredName:
                  type: string
                  description: The desired API subdomain.
                code:
                  type: string
                  description: The API description document source (API Blueprint or Swagger/OpenAPI).
            example:
              type: personal
              public: true
              desiredName: apisubdomain
              code: |
                FORMAT: 1A
                # API
      responses:
        '201':
          description: API Project created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ApiProjectCreated'
  /blueprint/get/{apiSubdomain}:
    parameters:
      - name: apiSubdomain
        in: path
        required: true
        description: An API subdomain.
        schema:
          type: string
        example: publicpersonalapi
    get:
      operationId: fetchBlueprint
      summary: Fetch Blueprint
      description: >-
        Fetch the API description document (API Blueprint or Swagger) for a
        particular API Project. Legacy — takes the `Authentication: Token <token>`
        header.
      tags: [Blueprint]
      security:
        - legacyToken: []
      responses:
        '200':
          description: The API description document source.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BlueprintEnvelope'
        '500':
          description: Internal Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LegacyError'
        '503':
          description: Infrastructure problem; please retry in a while.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LegacyError'
  /blueprint/publish/{apiSubdomain}:
    parameters:
      - name: apiSubdomain
        in: path
        required: true
        description: An API subdomain.
        schema:
          type: string
        example: publicpersonalapi
    post:
      operationId: publishBlueprint
      summary: Publish Blueprint
      description: >-
        Publish an API description document for a particular API Project,
        replacing the currently published revision. Legacy — takes the
        `Authentication: Token <token>` header.
      tags: [Blueprint]
      security:
        - legacyToken: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [code]
              properties:
                code:
                  type: string
                  description: The API description document source to publish.
            example:
              code: |
                FORMAT: X-1A
                HOST: http://api.example.com/

                # Example API

                Introduction.
      responses:
        '201':
          description: Published. Empty JSON object.
          content:
            application/json:
              schema:
                type: object
        '500':
          description: Internal Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LegacyError'
        '503':
          description: Infrastructure problem; please retry in a while.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LegacyError'
components:
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: >-
        HTTP Basic authentication with the Apiary account email and password. Used
        only on /authorization to mint, list and revoke tokens. Not available to
        users in IDCS-controlled teams.
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        RFC 6750 Bearer token. Generate at https://login.apiary.io/tokens or via
        POST /authorization. Sent as `Authorization: Bearer <token>`.
    legacyToken:
      type: apiKey
      in: header
      name: Authentication
      description: >-
        Legacy Apiary token header, sent as `Authentication: Token <token>` (note:
        the header is `Authentication`, not `Authorization`). Apiary labels the
        /blueprint/* group legacy. This is the same token value the Apiary CLI
        reads from the APIARY_API_KEY environment variable.
  schemas:
    Error:
      type: object
      description: The Apiary API error envelope — a single `error` string drawn from a closed enum.
      properties:
        error:
          type: string
          description: An error message.
          enum:
            - Unauthorized
            - Transport Layer Security Required
            - Token Invalid
            - Token Description Length Greater Than 30
            - Token Description Missing
            - Token Description Already Exists
            - Token Creation Failed
            - Token Deletion Failed
            - Token Retrieval Failed
            - User Query Failed
            - API Query Failed
            - Team ID Invalid
    LegacyError:
      type: object
      description: The error envelope used by the legacy /blueprint/* group — a boolean flag plus free-text message.
      properties:
        error:
          type: boolean
        message:
          type: string
      examples:
        - error: true
          message: Internal Error.
        - error: true
          message: Infrastructure problem; please retry in a while.
    Token:
      type: object
      properties:
        token:
          type: string
          description: A string granting a user authorization to protected resources.
        tokenDescription:
          type: string
          maxLength: 30
          description: A string, 30 characters or less, describing the token.
        tokenUrl:
          type: string
          format: uri
          description: A URL string representing a token resource.
    TokenList:
      type: object
      properties:
        tokens:
          type: array
          description: A list of Tokens.
          items:
            $ref: '#/components/schemas/Token'
    Team:
      type: object
      properties:
        teamId:
          type: string
          description: The team ID.
        teamName:
          type: string
          description: The team name.
        teamApisUrl:
          type: string
          format: uri
          description: A URL string representing an API list resource of team APIs you may access.
    User:
      type: object
      properties:
        userId:
          type: string
          description: The user ID.
        userName:
          type: string
          description: The user name.
        userApisUrl:
          type: string
          format: uri
          description: A URL string representing an API list resource of APIs you may access.
        teams:
          type: array
          description: A list of Teams.
          items:
            $ref: '#/components/schemas/Team'
    Api:
      type: object
      properties:
        apiName:
          type: string
          description: The API name.
        apiDocumentationUrl:
          type: string
          format: uri
          description: A URL string representing a documentation resource for an API.
        apiSubdomain:
          type: string
          description: The subdomain for the API.
        apiIsPrivate:
          type: boolean
          description: Is the API private?
        apiIsPublic:
          type: boolean
          description: Is the API public?
        apiIsTeam:
          type: boolean
          description: Is the API a team API?
        apiIsPersonal:
          type: boolean
          description: Is the API a personal API?
    ApiList:
      type: object
      properties:
        apis:
          type: array
          description: A list of APIs.
          items:
            $ref: '#/components/schemas/Api'
    ApiProjectCreated:
      type: object
      properties:
        status:
          type: string
          examples: [created]
        domain:
          type: string
          description: The API subdomain that was actually assigned.
          examples: [apiprojectsubdomain]
        url:
          type: string
          format: uri
          examples: ['https://apiprojectsubdomain.docs.apiary.io']
    BlueprintEnvelope:
      type: object
      properties:
        error:
          type: boolean
        message:
          type: string
        code:
          type: string
          description: The API description document source.