API Design

Shared Library

The Shared Library holds organization-wide schemas and responses that every project can reuse. Define common building blocks — an ErrorResponse schema, a standard NotFound response — once at the organization level, then link them into any API specification. Linked components stay connected to the library, so updates flow to consumers on their own schedule.

Where to find it

Open Settings → Shared Library. Managing the library requires the org:manage-governance permission (Admins and Owners); Members see the library in read-only mode. The page is available on all plans.

The page has two tabs — Schemas and Responses — each showing a searchable Shared Components list with the component name and its current version badge (e.g. v3).

The Shared Library settings page with the Schemas and Responses tabs

Creating a shared schema

  1. On the Schemas tab, click Create Schema.
  2. In the Create Shared Schema dialog, enter a Name (e.g. ErrorResponse, PaginatedResult), an optional Description, and the JSON Schema definition.
  3. Click Create Schema. Invalid JSON is rejected before saving.

Once created, the schema opens in an editor where you can maintain its Properties in a table (Add Property) and check the collapsible JSON Schema Preview.

Creating a shared response

  1. On the Responses tab, click Create Response.
  2. In the Create Shared Response dialog, enter a Name (e.g. NotFound, Unauthorized, ValidationError), an optional Description, and pick a Content Type (application/json, application/xml, text/plain, text/html, multipart/form-data, or application/octet-stream).
  3. Optionally define a Response Schema and an Example as JSON.
  4. Click Create Response.

The response editor additionally lets you edit the Response Body Schema (for JSON content types), response Headers (as JSON, e.g. {"X-Request-Id": "string"}), and the Example.

Versioning

Every shared component carries a version number. Saving a change increments it — while you edit, the header shows the pending bump (e.g. → v4 on save). Specs that link the component keep the version they linked, so a library update never silently changes a consuming spec (see Staying up to date below).

Deleting a component

Delete a component from its editor or via the trash icon in the list. The confirmation warns: "Are you sure you want to delete "{name}"? This action cannot be undone. Any specs referencing this schema will lose the link." Deletion is not blocked while the component is in use — the linked copies in specs remain, but they lose their connection to the library.

Using shared components in the API Designer

In the designer sidebar, the Shared section lists the components linked to the current specification, grouped into Schemas and Responses.

  1. Click the + button in the Shared section header.
  2. The Link Shared Components dialog opens: "Select components from the shared library to link to this specification." Components are grouped into the Organization Library (copied into this project when linked) and the Project Library. Search, select one or more, and click Link Selected.

Each linked component shows a scope badge — Org or Project — with a tooltip indicating which library it came from. Linking follows your spec editing rights (specs:write); creating or changing library components themselves still requires org:manage-governance.

You can also go the other way: promote a schema or response you built in a spec to the library via its Promote to Library action, making it reusable elsewhere.

The Link Shared Components dialog with organization and project library groups

Staying up to date

Links are pinned to the version you linked — library updates are opt-in per spec:

  • When a newer library version exists, the component shows a pulsing update indicator with the tooltip "Update available: v{linked} → v{current}".
  • Hover the component and click Accept update to move the link to the latest version.
  • To disconnect a component from the library entirely, use the Unlink from library hover action. The component's content stays in your spec; only the link is removed.
  • Schemas — building data structures inside a spec
  • Responses — defining what endpoints return
  • Components — spec-level reusable components
  • Style Guide — organization-wide design rules