Planning a new API

This is the path for an API that does not exist yet: no repo to import from, no Swagger file to upload, just an idea of what the thing should do. You end up with a spec that has been read, argued with, and corrected before a line of implementation exists.

Copilot does the typing. You do the deciding: it cannot change a spec without showing you exactly what it would change first.

Before you start

You need a workspace and editor access to it. A viewer can ask Copilot questions but is never offered the tools that write, so the approval step below will not appear.

1. Plan in prose first

Open Copilot (Copilot in the sidebar on the web, the centre tab on mobile) and describe the API in plain language before asking for any spec. Something like:

I’m building an orders service for a small e-commerce backend. Customers place orders, check status, and cancel within an hour. Staff can list and refund. Auth is a bearer token. What endpoints would you expect, and what am I likely to forget?

This step is worth its own turn. A model that has argued through the shape of the API writes a better first draft than one handed “make me an orders API”, and the things it says you are likely to forget (pagination, idempotency on create, a 409 for cancelling too late) are cheaper to decide now than to retrofit.

Nothing is written to your workspace yet. Copilot cannot touch a spec until you approve a specific change.

2. Let Copilot create the spec

When the shape looks right, ask for it:

Build that as a spec called “Orders API”.

Copilot calls create_spec, which makes the spec and selects it in one step. Like every write, it stops and shows you what it is about to do before it does it. Approve, and the spec exists in your workspace.

You can also start with an empty spec yourself (New spec → Create) and point Copilot at it. create_spec exists so an empty workspace is not a dead end, not because starting blank is wrong.

Starting from something instead

If there is an existing source, skip this section and use it. A real artifact beats a generated draft every time.

3. Edit by asking

Copilot works on one spec at a time. Say which one, or open it from the editor with the Copilot button in the header, which binds the conversation to the spec you have open and saves it from having to guess.

Useful things to ask:

• “Which endpoints do not document a 401?”
• “Add a 401 response to every endpoint behind auth.”
• “The cancel endpoint should return 409 if the order shipped. Add that.”
• “Compare the auth on this spec and the payments one.”
• “Extract the repeated address object into a shared schema.”

Reads happen immediately. Writes stop and wait for you. Anything Copilot can change you can also change by hand: see Editing endpoints and Schemas.

4. Read the diff before you approve

Every write opens an approval showing what would change, worked out by running the real tool against a database that captures the write instead of performing it. The preview is the behaviour, not a description of it.

What to look at:

• Breaking changes lead the list and are marked. Removing an endpoint, removing a response, tightening a type: anything already calling your API may stop working. A diff with breaking changes takes a second, deliberate confirmation.
• “and N more changes not listed here” means the list is capped, not that the change is small. A whole-spec replace can run to hundreds of changes.
• Arguments, on changes with no diff to show (creating a spec, calling a live endpoint), are the whole story. Read them.

Then decide:

• Approve applies it. The previous version is snapshotted to spec history first, so a change you regret can be rolled back.
• Reject changes nothing. Give a reason and Copilot reads it and will not propose the same thing again. “We version that endpoint separately” saves you the same argument twice.

Dismissing is not a decision. The dialog waits, and a conversation left waiting on an approval can be reopened later and answered then.

5. Check the work

Copilot is a fast drafter and an unreliable reviewer of its own output. Before you call the spec done:

• Open the flow builder and look at the shape. Paths that surprise you are usually paths the model invented.
• Run Analyze for missing descriptions, undocumented responses, and inconsistent operationIds.
• Run a few endpoints against a real or mock server. A spec that has never been executed is a guess.

6. Hand the spec to something

A finished spec is an input, not a deliverable:

• Export it as JSON or YAML.
• Share a hotlink so consumers can read it without an account.
• Connect the MCP server so your coding agent writes the implementation against the spec you just reviewed.

Code generation is not shipped yet. The API Generator extension is listed in the extensions hub, and its page describes server stubs and client SDKs in several languages. Nothing is wired behind it today: there is no generator to run and no output to download. Until it lands, generate code from an exported spec with your own toolchain, or point a coding agent at the spec over MCP.

What Copilot will not do

• Apply anything you did not approve. Approval is per change, and the tool and its arguments are read back from the server, never from the browser.
• Write your implementation. It authors the spec and can describe a fix precisely enough to become a GitHub issue. It does not write the service.
• Exceed your own access. It runs with your workspace role. A viewer’s Copilot is read-only, and the role is checked again when a change is applied, not just when it is proposed.
• Treat your spec as instructions. Descriptions in a spec are written by whoever wrote the API. Copilot reads them as data; text in there telling it to do something is reported, not obeyed.

Limits

Copilot sessions are metered per plan, counted per conversation started rather than per message, so follow-up questions in the same conversation are free. Steps within a single turn are capped too, which is what bounds the cost of one request. See Pricing for the numbers on your plan.