All documentation

API reference

Where to get the OpenAPI description and how to use it alongside the guides.

The API reference is a machine-readable description of the documented PCIFIC API addresses. It is written in OpenAPI 3.1 (a standard file format for describing web APIs). It lists routes, every field each request accepts, the shape of every nested object, responses and errors. It is built from the same field tables as the guides, so the two always agree.

Operations are tagged by product. Shared error responses and headers use components (named definitions reused by reference). Objects whose keys are your own, such as the category schema you upload, Orbit item, details and finalListing, Safeguard listing and the item your lookup answers, are marked customer-defined. They hold your shop's published listing fields, so they stay open in this file: use your published category JSON Schema to generate those types. The tool response envelopes describe statuses, questions, sources and photos.

Where it is

The description is at https://business.pcific.ai/openapi.json. Anyone can read it, and no key is needed. Every JSON request body carries a request example, the same one the guides show where a guide has one, and most carry several more under examples. An example that needs something first, such as a published category or an id from an earlier answer, says so in its description.

Download it
curl -o pcific-openapi.json https://business.pcific.ai/openapi.json

How to use it

  • Import it into an API client such as Postman or Insomnia, using the import from a link or from a file option. The documented addresses, their fields and a ready-made example request for each JSON body appear.
  • Generate a typed client for your language with an OpenAPI code generator. Every accepted field and nested object is typed. Generate it again when PCIFIC updates the description.
  • Send requests from the client with a key in the Authorization header, as the guides describe. Use a test key while you build, and a live key only on your production server.
  • Read Errors, limits and retries for the shared errors and the rules for sending a request again safely.

What it describes

  • Each address, its method and what it does.
  • The key permission each address needs.
  • Every field each address accepts and answers, with nested objects typed down to their own fields.
  • A request example for every JSON request body.
  • The errors each address can return, including 429 RATE_LIMITED with its Retry-After header.
  • Where an address takes an Idempotency-Key header, so a repeated request is answered once.

Words used on this page

  • OpenAPI: a standard file format that describes web addresses, the fields they take and the answers they give.
  • API client: a program, such as Postman or Insomnia, that sends requests to an API and shows the answers.
  • Typed client: code generated from the description, so a program knows the type of each field.