--- title: "API endpoint development brief writer" type: "prompt" url: "https://useaiblocks.com/prompts/build-first-api-endpoint-builder-prompt" updated: "2026-11-03" first_published: "2026-10-25" job: "Build and ship software" tested: true instructions: "https://useaiblocks.com/skills/build-first-api-endpoint-builder-prompt/SKILL.md" --- # API endpoint development brief writer > Build your first API endpoint. Paste one prompt into Claude Code to make two small Next.js routes and learn how a server works. Paste one prompt into Claude Code. It builds two small API routes in your Next.js project, a GET ping and a POST echo, then explains each step in plain English. A second prompt briefs your own first endpoint before any code is written. Free prompt for the job "Build and ship software" · Level: beginner · Thinking: medium · Tested · Updated 2026-11-03 ## Links - Page: https://useaiblocks.com/prompts/build-first-api-endpoint-builder-prompt - Instructions (SKILL.md): https://useaiblocks.com/skills/build-first-api-endpoint-builder-prompt/SKILL.md - All files (zip): https://useaiblocks.com/skills/build-first-api-endpoint-builder-prompt.zip - JSON version: https://useaiblocks.com/prompts/build-first-api-endpoint-builder-prompt.json - In your AI: connect https://useaiblocks.com/mcp and ask "Use AI Blocks to get build-first-api-endpoint-builder-prompt" ## What it does An API endpoint is a web address that does a job and sends back data instead of a page. Almost every app, tool and AI agent talks to others this way. If you have never built one, the words around it make it hard to start. This prompt is a short practice run for your first API endpoint in Next.js. It asks your coding AI to build a ping route that says the server is alive, and an echo route that sends back what you send it. The echo route also replies with a clear error when the data is not valid. The AI then explains, in plain English, what happens when each one is called. The second prompt is for your own first endpoint. It makes the AI write a brief first: the request checks, the error replies and the tests. You read it and approve it before any code is written. ## What you give it - A Next.js project that uses the App Router, open in your coding AI - Node.js and npm installed on your computer - Claude Code or a similar coding AI that can edit your project files - What your own first endpoint should do, in one or two sentences (optional) ## What you get - A GET ping route that returns the time and a status message - A POST echo route that sends your data back and replies with clear errors for bad input - A plain-English explanation of what happens when each route is called - A list of every file the AI created or changed - Test steps for Mac, Linux and Windows ## Example: what goes in and what comes out ### What goes in - A Next.js project that uses the App Router - Node.js and npm installed - Claude Code or a similar coding AI - A sentence on what your own first endpoint should do (optional) ### Before you start - A paid Claude plan or an Anthropic API account for Claude Code ### What comes out - **ping route**: A GET route at app/api/ping that returns a status, the current time and a short message. - **echo route**: A POST route at app/api/echo that returns your data, with 400 and 413 replies for bad input. - **Plain-English explanation**: What happens on each call, what localhost and 3000 mean, and why the files sit where they do. - **File list**: Every file created or changed. No packages are installed and nothing is deployed. - **Own-endpoint brief**: The request checks, error replies, needs and tests for your own endpoint, ready for you to approve. ## The layout of every result ```text Check: Files created: app/api/ping/route.ts, app/api/echo/route.ts Other files changed: Plain-English explanation: 1. What happens when you open /api/ping 2. What happens when something posts to /api/echo 3. What localhost and 3000 mean 4. Why the files live in app/api 5. What the 400 and 413 replies are for How to test: Optional brief for your own endpoint: Purpose | Request and checks | Success reply | Error replies | What it needs | Tests ``` ## Use it when - You use Claude Code or Cursor and want to see what an API endpoint really is. - A developer or tool asks you for "an endpoint" and you want to know what that means. - You plan to build a small tool for your store and want one working route to learn from. - You are about to ask an AI for a real endpoint and want to practise the steps first. ## Skip it when - You want to test endpoints you already have: use the API test suite builder. - Your app is a mobile app that needs a server: use the Expo API route builder. - You want a Slack bot, not a web route: use the Slack bot build brief writer. - You do not have a Next.js project with an app folder and Node.js installed: set those up first, or ask your AI which steps change for your stack. ## How to use it 1. Open your Next.js project in Claude Code. Check that it has an app folder and that Node.js is installed. 2. Copy the Part 1 prompt from the skill and paste it into Claude Code. Claude Code needs a paid Claude plan or an Anthropic API account. 3. Read the explanation, then run npm run dev in your terminal. This starts the project on your own computer. 4. Open localhost:3000/api/ping in your browser. Then test the echo route with the command in Part 2. 5. Send the echo route text that is not valid JSON, and check you get the 400 error. 6. When ready, paste the Part 3 prompt with your own endpoint idea. Read the brief and fix it before you say OK. ## What to do next - [RoadRunner traffic test scenario writer](https://useaiblocks.com/skills/driving-test-scenario-writer): Build it - [API test suite builder](https://useaiblocks.com/skills/api-test-suite-builder): API test suite builder ## Instructions (SKILL.md) ## First API endpoint prompt for Next.js This prompt is for a person who is not a developer and wants to see what a server does. You paste it into Claude Code (or another coding AI that can edit files in your project). It builds two tiny routes and explains them. It is a practice exercise. It does not build a feature for your business. To review the two new routes afterwards, use the Code change reviewer. Part 3 is the bridge to your own first endpoint. Not for: testing endpoints you already have (use the API test suite builder), a mobile app that needs a server (use the Expo API route builder), a Slack bot (use the First Slack Bot coding prompt), or a project that is not Next.js with an app folder. The "Before you start" list mentions MISSING lines and CHECKS MISSED. Ignore those two labels here. This prompt has neither section: if something is missing, say exactly what and stop. After this, the default next step is the Code change reviewer. ### Before you start Use the material below to do this job. If facts or tool access are missing, explain what you can finish and what must wait. **What you need** (use your own material or the linked skill): - **A codebase** (yours): a project's code, in a folder or repo the AI can open. How to start: 1. **Look first.** Use what they've already attached, pasted or put in their about-me note. In a coding assistant with file access, look in the project too for these by name. 2. **Check what's missing.** Look for a codebase. They can attach files, paste the details, or share a file path your assistant can read. Ask only for missing facts that change the result. If they ask you to start with what they have, complete the parts you can and mark the gaps. 3. **Do the job.** Follow the method with the facts and tools you have. Mark each gap with `MISSING:` where it belongs and never invent a fact to fill it. Keep the answer tight: say each point once and merge steps that give the same thing. In CHECKS MISSED, list checks that failed or could not run. If every required check ran and passed, write “none”. ### What you need first This is a local practice run. The echo route sends back whatever it receives, so never deploy it. - A **Next.js project that uses the App Router** (it has an `app/` folder, or `src/app/`). Next.js is the web framework this prompt is written for. - **Node.js and npm** installed, so you can run the project on your own computer. - **Claude Code** or a similar coding AI with access to the project folder. Claude Code needs a paid Claude plan or an Anthropic API account. Check Anthropic's current pricing and sign-in options. - A terminal window. - For the optional Part 3 only: your own endpoint idea, written in one or two plain sentences. Without it, skip Part 3. No project yet? Make a throwaway one with the setup command on the Next.js website. That installs software on your computer, so do it yourself and only if you want to. Do not ask the AI to install anything for you here. If your project uses the older `pages/api` folder, or is not Next.js, tell the AI before it starts. It should say what changes and ask before it goes on. ### Part 1: Paste this into your coding AI ``` I'm learning how servers work. I'm not a developer. First, look at my project and tell me whether it uses the Next.js App Router (app/ or src/app/). If it doesn't, stop and tell me what you found. Then do these things. Don't install packages, change config files or deploy anything. 1. Create a GET route at app/api/ping/route.ts that returns JSON: { "status": "ok", "timestamp": , "message": "Your server is alive" } 2. Create a POST route at app/api/echo/route.ts that: - reads the JSON body of the request - returns { "received": true, "original": } - if the body isn't valid JSON, returns status 400 with { "error": "Body must be valid JSON" } - if the body is larger than 10 KB, returns status 413 with { "error": "Body too large" } 3. After you create both files, explain in plain English: - what happens step by step when I open localhost:3000/api/ping in my browser - what happens when something sends a POST to localhost:3000/api/echo - what "localhost" means and what "3000" means - why these files live in the app/api folder - what the 400 and 413 replies are for Keep it simple. Then list every file you created or changed. ``` ### Part 2: Check that it works 1. In your terminal, run `npm run dev`. This starts the project on your computer only. 2. Open `http://localhost:3000/api/ping` in your browser. You should see JSON with `status`, `timestamp` and `message`. 3. Test the echo route from a second terminal. - Mac or Linux: `curl -X POST http://localhost:3000/api/echo -H "Content-Type: application/json" -d '{"name":"Sam","test":true}'` - Windows PowerShell: `Invoke-RestMethod -Method Post -Uri http://localhost:3000/api/echo -ContentType "application/json" -Body '{"name":"Sam","test":true}'` 4. You should get your data back with `received: true`. Now send text that is not JSON, such as `hello`. You should get the 400 reply. If a step fails, paste the error message back to your AI and ask what it means. ### Part 3 (optional): Brief your own first endpoint Once the practice routes work, paste this. It makes the AI plan first and code second. ``` I want a real endpoint for my project: . Don't write code yet. First write a short brief with: - what the endpoint does and who calls it - the request: method, path and the fields it accepts, with the checks for each field - the success reply - the error replies: bad input (400), not allowed (401 or 403), not found (404), too many requests if it applies, and a server error (500). Say what each one returns. - anything it needs that I may not have: a database, a key, a login - a list of tests: one for success, one for each error Wait for my OK before you write any code. Don't add packages or connect any outside service without asking. ``` Read the brief and fix anything wrong before you say OK. ### What good output looks like The AI should hand back, in this order: Check (App Router found or not, and what it saw), Files created, Other files changed (or none), the Plain-English explanation, How to test, and the optional brief for your own endpoint. - Two new files, `app/api/ping/route.ts` and `app/api/echo/route.ts`, and a list of every file the AI touched. - A plain-English explanation that answers all five questions in Part 1. - No new packages, no changed config, nothing deployed. ### Rules for the AI - Look at the project first. Do not guess paths. - Do not install packages, change config, start background jobs or deploy unless the person says so. - Do not claim you ran the project or a test unless you did. Say what the person should run. - If something the person needs is missing, say exactly what, and do not make it up. - Keep every explanation short and free of jargon. - Remind the person once that the echo route sends back whatever it receives, so it is for local practice. They should not send passwords or secrets to it, and should not deploy it as is. ### What you just built - Two API endpoints. An API endpoint is a web address that does a job and returns data instead of showing a page. - A GET endpoint: your browser asks, the server answers. - A POST endpoint: a program sends data, the server checks it and answers. - This is the same pattern that agents and apps use to send and receive work. ### After this When you've handed it back, suggest what they could do next in one short question. It's a suggestion: if they're done, that's fine. Offer these, and say they can type their own: - The [RoadRunner traffic test scenario writer](https://useaiblocks.com/skills/driving-test-scenario-writer). It takes the code change. - The [API test suite builder](https://useaiblocks.com/skills/api-test-suite-builder). It takes the code change. If they pick one and that skill is added here, carry straight on with what you just made. If not, give the link and say what to bring.