# Apiary

> Apiary is an API design and documentation platform, now part of Oracle Cloud Infrastructure. It uses API Blueprint and Swagger/OpenAPI to produce interactive documentation, automatically provisioned mock servers, contract testing and collaborative design workflows. Apiary publishes its own public API at https://api.apiary.io.

Generated by API Evangelist on 2026-09-02. Apiary does not publish an llms.txt of its
own — /llms.txt returned 404 on apiary.io, api.apiary.io, help.apiary.io,
apiblueprint.org, jsapi.apiary.io and login.apiary.io on that date. This file is
generated from Apiary's own published surfaces and from the artifacts in this
repository, and every link below was fetched and returned HTTP 200 unless noted.

## What an agent needs to know first

- Base URL: `https://api.apiary.io`. TLS is mandatory; a plaintext request is answered 403 `{"error": "Transport Layer Security Required"}`.
- There are NINE operations, across four groups, and THREE different authentication schemes:
  - `/authorization` (mint, list, revoke tokens) takes HTTP **Basic** account credentials. Not available to accounts in Oracle IDCS-controlled teams.
  - `/me`, `/me/apis`, `/me/teams/{teamId}/apis` take `Authorization: Bearer <token>` (RFC 6750).
  - `/blueprint/create`, `/blueprint/get/{sub}`, `/blueprint/publish/{sub}` take the legacy header `Authentication: Token <token>` — the header name is `Authentication`, not `Authorization`.
- Tokens are unscoped and account-wide. Apiary's own words: "a token is like a password and will give anyone with this token access to fetch and publish to your documentation."
- Apiary publishes **no OpenAPI for its own API**. Its contract is an API Blueprint / API Elements document served at https://jsapi.apiary.io/apis/apiary. An OpenAPI 3.1 translation of it is maintained in this repository.
- Apiary labels the `/blueprint/*` group **legacy** — and those are the only operations that read or write API description documents.
- No pagination, no idempotency keys, no request ids, no versioning, no 429, no status page.

## API operations

- getMe — `GET /me` — the authenticated user and their teams
- listMyApis — `GET /me/apis` — API Projects the caller can access
- listTeamApis — `GET /me/teams/{teamId}/apis` — one team's API Projects
- fetchBlueprint — `GET /blueprint/get/{apiSubdomain}` — read a project's API description document
- publishBlueprint — `POST /blueprint/publish/{apiSubdomain}` — replace it (DESTRUCTIVE, no API-level undo)
- createApiProject — `POST /blueprint/create` — create a project (not idempotent; no delete operation exists)
- createAuthorizationToken — `POST /authorization` — mint a token (Basic auth)
- listAuthorizationTokens — `GET /authorization` — list token descriptions (Basic auth)
- deleteAuthorizationToken — `DELETE /authorization` — revoke a token (Basic auth)

## Before you write

Before calling `publishBlueprint`, call `fetchBlueprint` and keep the result. Apiary
keeps version history and exposes a per-project Atom feed with a diffing UI, but
rollback is a manual copy-and-save in the web editor — there is no restore operation
in the API and no stated retention window. Deleting an API Project is web-UI only and
Apiary states it "can't be undone".

## Documentation

- [Apiary API reference](https://apiary.docs.apiary.io): Apiary's own API, documented in Apiary. JavaScript-rendered.
- [Apiary API description document](https://jsapi.apiary.io/apis/apiary): the machine-readable source behind that page (JSON / API Elements).
- [Apiary Help](https://help.apiary.io): the product documentation root.
- [Mock Server](https://help.apiary.io/tools/mock-server/): private mock URLs, the `Prefer: status=` header, and the 120/5000 requests-per-minute limits.
- [Apiary CLI](https://help.apiary.io/tools/apiary-cli/): `gem install apiaryio`, `apiary fetch`, `apiary preview`, `apiary publish`.
- [Local API testing with Dredd](https://help.apiary.io/tools/automated-testing/testing-local/)
- [Continuous API testing](https://help.apiary.io/tools/automated-testing/testing-ci/)
- [Embed documentation](https://help.apiary.io/tools/embed/): the `Apiary.Embed` browser component.
- [Version history](https://help.apiary.io/tools/version-history/): per-project Atom/RSS change feeds and the diffing UI.
- [API Blueprint specification](https://apiblueprint.org/documentation/specification.html)

## Product

- [Apiary](https://apiary.io)
- [Plans](https://apiary.io/plans): Free (marked deprecated by Apiary), Standard, Pro. No prices are published.
- [Sign in](https://login.apiary.io) / [Register](https://login.apiary.io/register)
- [Tokens](https://login.apiary.io/tokens)
- [Terms of service](https://apiary.io/tos) / [Privacy](https://apiary.io/privacy)

## Open source

- [apiaryio on GitHub](https://github.com/apiaryio): archived 2024-11-08; all repositories read-only.
- [API Blueprint](https://github.com/apiaryio/api-blueprint) — the description language Apiary authored (MIT)
- [Dredd](https://github.com/apiaryio/dredd) — contract testing runner (npm `dredd` 14.1.0, 2021-11-16)
- [Gavel](https://github.com/apiaryio/gavel.js) — HTTP transaction validator (npm `gavel` 10.0.4, 2021-12-09)
- [apiary-client](https://github.com/apiaryio/apiary-client) — the CLI (rubygems `apiaryio` 0.17.0, 2021-10-21)

## Change signals

- [Apiary API change feed (Atom)](https://apiary.docs.apiary.io/feed): newest entry 2019-07-25; feed last updated 2020-03-02.
- [Apiary blog](https://blog.apiary.io): newest post 2019-02-06.

## Machine-readable artifacts in this repository

- openapi/apiary-apiary-api-openapi.yml — OpenAPI 3.1 translation of Apiary's published description
- api-description/apiary-api-description.json — Apiary's own description document, saved verbatim
- json-schema/ — the six response schemas Apiary publishes, extracted verbatim (draft-04)
- authentication/apiary-authentication.yml — the three schemes
- conventions/apiary-conventions.yml — pagination, idempotency, versioning, reversibility
- errors/apiary-problem-types.yml — the closed error enum and the two incompatible envelopes
- data-model/apiary-data-model.yml — User, Team, API, Token and how they link
- lifecycle/apiary-lifecycle.yml — deprecations, legacy group, no status page, no SLA
- rate-limits/apiary-rate-limits.yml — the mock-server limits and the API's undocumented ones
- plans/apiary-plans-pricing.yml — the three tiers, with no published prices
- sandbox/apiary-sandbox.yml — the mock server, which is the product
- packages/apiary-packages.yml — every first-party package with its version and release date
- cli/apiary-cli.yml — the Apiary CLI command surface
- components/apiary-components.yml — Apiary Embed and the browser console
- changelog/apiary-changelog.yml — the nine published change entries
- conformance/apiary-conformance.yml — RFC 6750 yes; RFC 9457, RFC 9331, RFC 8594, OAuth2, OIDC no
- mcp/apiary-mcp.yml — a derived candidate tool surface; Apiary ships no MCP server

## Not available

Apiary serves none of: /.well-known/security.txt, /.well-known/openid-configuration,
/.well-known/oauth-authorization-server, /.well-known/oauth-protected-resource,
/.well-known/api-catalog, /.well-known/ai-plugin.json, /.well-known/agent-card.json,
/.well-known/agent.json, /llms.txt — all 404 on all six hosts as of 2026-09-02.
There is no MCP server, no A2A agent card, no GraphQL endpoint, no gRPC/protobuf
contract, no WSDL, no AsyncAPI, no webhook catalog, no status page and no published
SLA.