What does API-first ask of a designer?

API-first asks the designer to draw the contract before the screen. The contract has five parts: names and descriptions, defaults, error responses, confirmations, and what the system does with input it does not recognise. An agent using the product never sees the screen. The agent sees only the contract, and the agent follows the contract to the letter.

Apps AS builds products where agents are as common a user as people. This article draws on how the CMS in Munin, Apps AS' own customer platform, is set up for the publishing agent that writes the drafts on apps.no, and on how outbound calls are set up in Threll.ai, as read on 12 October 2026.

What does API-first mean?

API-first means a product's functions are built as a programming interface first, and the screens are built on top of that same interface afterwards. Anything a person can do on the screen, another program can do through the API.

The term is older than agents. What is new is who calls the API. The caller used to be a developer who read the documentation and wrote the code once. Now the caller is often an agent that reads the description on every call, picks an action from the text and asks nobody when the text is unclear.

Why is the API now the designer's job?

The API is the designer's job because the API is the only interface the agent meets. An API shaped like the database worked as long as the caller knew how the system was built. An agent does not know that, and the agent fills the gaps by guessing.

Kaleb Pomeroy of the security company SpecterOps described in July 2026 how the team behind the BloodHound tool rebuilt an MCP server, the server that gives agents tools under the Model Context Protocol standard. The first version mirrored the API. The finished version had a few simple calls built around what the agent was trying to do, and tools were added back only where agents exposed a gap in the workflow. That method is design work: watch the use, remove choices and add back what was missing.

Which five things must a designer deliver in an API-first product?

A designer must deliver five things in an API-first product. Each of the five has a counterpart in screen design that the designer already knows.

The screen equivalent	What the designer delivers in the API	Example from Apps AS
The help text	A name and description for every action and field	The field descriptions in the article collection in Munin
The preselected option in a form	The default when a field is left out	The default language of the apps.no CMS
The error message	An error response that tells the caller what to do next	The error codes for text edits in Munin
The confirmation dialog	Two operations: prepare, then execute	Outbound calls in Threll.ai
The form validation	What the system does with input it does not recognise	Unknown block types on the article page

Why is a field description design work?

A field description is design work because the description is the only thing the agent reads before filling in the field. The description does the job that help text, a placeholder and an example do on a screen.

The descriptions in the article collection on apps.no are written as instructions. The alt text field says the text should describe what is literally in frame and not repeat the title. The sources list says the word "Link:" should not appear before the links, because the label otherwise becomes repeated noise on every line. Both sentences stop an easy mistake before it happens.

The same rule applies to channels. The customer agent in Munin has one description per channel. On SMS, a reply must stay under 160 characters and contain no markdown. The design specification for the SMS channel is two sentences of text.

Why is a default a design decision?

A default is a design decision because the default decides what happens when the caller does not choose. A person sees the preselected option in the form. An agent that leaves a field out sees nothing.

The CMS that apps.no publishes from has English (en-US) as its default language. A Norwegian article created without a language is stored as English, with no error. The publishing agent on apps.no therefore has a dedicated rule to state the language on every create. That rule is a patch over a design decision. A default that can give a wrong result without warning should have been a required field.

What should an error response tell an agent?

An error response should tell the agent what to do next. An error message for a person can be vague, because the person sees the screen and tries again. An agent has only the text of the response.

Munin separates errors that call for different next steps. When the agent tries to replace a piece of text that does not exist, the CMS returns cms_replacement_no_match. When the text occurs in several places, the CMS returns cms_replacement_ambiguous. The first error means the agent must read the article again. The second means the agent must include more of the surrounding text. Every update is also sent with the version number the agent read, so a change a person made in the meantime is not overwritten.

The image tool in Munin is designed for a caller that retries. An identical request within 15 minutes returns the first image instead of generating a new one. An agent that thinks the call hung does not end up with two images and two bills.

Why must actions that cannot be undone be split in two?

Actions that cannot be undone must be split into two operations because otherwise the agent decides and executes in the same call. On a screen, the confirmation dialog is the designer's tool. In an API, the tool is a preparing operation that returns a summary and a one-time token, and an executing operation that requires the token.

Threll.ai, the voice agents Apps AS develops, uses that model for outbound calls. The agent prepares the call and gets back a summary of which agent is calling, from which number, to which number and with which script. The call is placed only when someone confirms with the token. Which actions should be split this way is covered in Which processes can be automated?

What should a system do with input it does not recognise?

A system should say so when it receives input it does not recognise. A form can make an invalid choice impossible. An API receives whatever the caller sends, and has to decide what happens to the rest.

The article page on apps.no renders seven block types. A block type the page does not recognise is skipped without an error, and its content disappears from the page. That choice makes the page robust, and it makes the error invisible to the agent that wrote the block. The same contract has two more deliberate rules: a statistic block without an explanation is not shown at all, and a markdown blockquote in body text is shown as a callout box, not as a quotation. The rules work only because they are written in the description the agent reads.

What is left of screen design?

Screen design remains wherever a person has to approve, monitor or take over. That surface is used less often and matters more. How the machine surface and the human surface split a product between them is covered in Salesforce moved the interface out of the product. The price has to follow. How API-first connects to the pricing model is covered in the anchor article Architecture, design and price are the same decision. Why the drawing is the cheapest place to change a technology choice is covered in Design is where a technology choice gets cheap.

Send us the field that is most often filled in wrong

Take the field in your API that is most often filled in wrong, and write down the description it has today. Send the description and one example of a wrong entry to hello@apps.no. We will reply with a new description, or tell you the field should have been required.