Developers

Ask a store what it can make, from your own assistant.

Every store on Specify answers an API built for AI assistants. It gives the same answer the store gives a buyer. Nothing is guessed on the way.

The same answer as the store

An assistant asks if a store can make something. The API asks the same code the store asks.

So the two answers stay the same. A test sends both the same question and compares the replies byte for byte.

A no comes with the store's own words. A price is the store's own figure, or no figure at all.

Five routes

Each path starts with the store's name, its slug. No route needs a key.

GET /api/agent/v1/{merchantSlug}/capability
What the store can make: options, units and ranges. And the products you can ask about.
POST /api/agent/v1/{merchantSlug}/offer
Send chosen options. Get back yes or no, the reasons, and the price.
POST /api/agent/v1/{merchantSlug}/offer/from-intent
Send a sentence instead. Get the same answer, and what was understood.
POST /api/agent/v1/{merchantSlug}/opportunities
Send a request for something the store does not offer yet. The store answers it.
POST /api/agent/v1/{merchantSlug}/orders
Place an order a buyer asked for, at the price they agreed.

The OpenAPI document

The routes are described in one OpenAPI document. It is made from the code, so it cannot drift from it. It covers these five routes and nothing else.

https://api-dev.specify.digital/openapi/agent.json

Open the OpenAPI document

What you can rely on

  • No invented prices

    A price is fixed, worked out, or needs a person. In the last case, no number is sent.

  • One key, one order

    Each order carries a key your code makes up. Send it again after a lost reply, and you get the same order back.

  • The price the buyer agreed

    Say the total the buyer agreed to. If the price has moved, nothing is placed. The reply gives the new total.

  • Errors you can act on

    Every error has a fixed code, and each code says what to do next. Codes are never renamed.

  • Changes only add

    The version is in the path. Within a version, changes only add. A test checks every change against the last published shape.

  • Questions, not a dump

    An assistant can ask about an option the store does not show. It cannot list them all.

Keys

The agent API needs no key. It is built for any assistant. Each route has a limit per address. A busy reply says when to try again.

A store's own systems are different. Owners and admins make an API key for each one. They do it in the admin, under API keys. A key is shown once and can be revoked.

Not built yet

The API document lists these, and so do we.

  • An assistant cannot pay for the buyer. The buyer pays on the store's own payment page.
  • A sentence is read one turn at a time. There is no back and forth.
  • An assistant places an order a buyer asked for. It does not decide to buy.

Try it against a store of your own

Set up a store with one product and its options. Then point your assistant at it.

Create your store Read how it works

To sign up, we ask for your work email and your company name.