API Backends

Build custom APIs with Hono, test them in the API console, and store data in D1 or your own Postgres database

An API Backend is an app in your project that serves your own API. It’s built with Hono and TypeScript, and the AI agent writes the routes, database schema, and tests for you. Instead of a visual preview, the builder opens an API console where you can see every endpoint, send test requests, and read the logs.

Your mobile apps, web apps, and websites in the same project can share one API Backend.

Adding an API Backend

API Backends live inside a project. To add one:

Open your project and click Add app.
Under Backend & data, choose API Backend.
Choose a database (see below).
Describe what the API should do and click Create app, or click Create without a prompt to start from the default setup.

You need the Editor role or higher to add apps to a project. A project can hold more than one API Backend.

Choosing a database

Option	What you get
D1	A managed SQL database at the edge, created for you. This is the default. See D1 database.
Supabase	A dedicated, managed Postgres database.
External Postgres	Connect a Postgres database you already have.
None	No database. You can add one later.

For External Postgres, enter a Development connection URL (it starts with postgres:// or postgresql://). You can also add a Migration URL (optional) if migrations should use a different connection. Credentials are encrypted when they’re saved. You connect the staging and production databases later, from the Database tab. See External Postgres.

To add a database to an API Backend created with None, open Integrations and go to the Database tab. Choose Provision Cloudflare D1, Provision Supabase, or Connect Postgres. Once a database has data in it, you can’t switch it to a different provider automatically.

How your API is built

The agent follows a consistent structure, so your API stays easy to test and document:

Hono on Cloudflare Workers. Your API runs on the Workers runtime, which has no filesystem and doesn’t support long-running processes.
OpenAPI routes. Each route declares its request and response schemas, and the API serves an OpenAPI document at /doc. The API console and API Docs are both built from this document, so a route only shows up there if it’s declared this way.
Versioned paths. Public routes live under /v1. /doc and the /healthz health check are always public.
API keys by default. Every other route requires an API key, including new ones the agent adds.
Database migrations in your repo. Schema changes are written as migrations and saved with your code, so every environment gets the same schema when you publish.
Tests. The agent can write and run tests that use the same Workers runtime.

Environment variables and secrets

Store secrets such as third-party API keys as environment variables in Settings, not in your code. For an API Backend, every variable is stored as a secret and is available only to your API at runtime. When you add a variable, choose which environments it applies to, so development, staging, and production can each use their own value.

Draftbit sets your database’s connection details for each environment itself. With External Postgres, the connection URL is in DATABASE_URL and the migration URL is in DATABASE_MIGRATION_URL. While the app has a database, those names are reserved, so you can’t add your own variables with them.

API console

The API console is the main view of an API Backend. It has three parts: Endpoints on the left, the request playground in the center with Request Logs below it, and the agent on the right. On a phone, use the tabs along the bottom (Endpoints, Console, Agent) to switch between them.

Endpoints

The Endpoints list updates on its own as the agent adds or changes routes. Endpoints are grouped by tag, or by the first part of their path, and each shows its method, path, and summary. Use Search endpoints… to filter by path, method, summary, or tag.

If the list is empty, check the message it shows. The development server may still be starting, or the API may have no routes yet. If the OpenAPI document is missing or invalid, ask the agent to fix it.

Sending requests

Select an endpoint to open it in the playground. Fill in any path parameters in the request bar, then click Send. Requests always go to your development server.

Tab	Use it to
Params	Add query parameters.
Headers	Add request headers. `Content-Type` is filled in for requests with a body.
Body	Edit the JSON body. It starts with the example from the endpoint’s schema, and Reset to example restores it.
Auth	See the development API key the playground attaches for you. Turn on Send without API key to check that the endpoint rejects unauthorized requests.

The response shows the status, how long the request took, and the response size, with Body and Headers tabs. Click Copy as cURL to copy the request as a command you can run elsewhere. The copied command has a placeholder where your API key goes.

The playground remembers each endpoint’s request and last response while you switch between endpoints. Viewers can browse endpoints but need the Editor role to send requests.

Request Logs

Open Request Logs from the bar at the bottom of the playground.

Requests lists recent requests, newest first, with the method, path, status, duration, and time. Expand a request to see the logs it produced. Your latest request from the playground is highlighted.
Raw shows the full development server log.

API Docs

API Docs in the builder navigation shows documentation generated from your API’s OpenAPI document. For each endpoint you get its parameters, request body, responses, and whether it requires an API key. Wide screens also show a cURL example you can copy. Everyone with access to the app can read API Docs.

D1 database

D1 is a managed SQL database from Cloudflare. When your API Backend uses D1, Draftbit creates the database for you. Your API reaches it directly, so there’s no connection URL to manage.

Each environment has its own database:

Development is created with the app and is the one the agent and the API console use.
Staging and Production are created the first time you publish to that environment.

Browsing your data

There are two ways to open the D1 workspace:

On your project page, click Manage D1 on the API Backend’s card.
In the builder, open Integrations and go to the Database tab.

You need the Editor role or higher. Pick an environment, then use the sections:

Section	What it shows
Overview	The database’s storage, table count, and settings.
Tables	Your tables. Select one to browse its first 100 rows.
SQL	Run SQL queries. Results show up to 500 rows.
Metrics	Reads, writes, rows read and written, and the queries using the most database time, for today, the last 7 days, or the last 30 days.

Table browsing is read-only. In SQL, a query that can change data or schema needs a second click to confirm. Before you can run SQL against Staging or Production, Draftbit asks you to confirm, and for production you type PRODUCTION.

External Postgres

With External Postgres, your API Backend uses a Postgres database you host yourself, with any provider that gives you a postgres:// or postgresql:// connection URL. Draftbit doesn’t create or manage the database. It stores the connection details, gives them to your API, and runs your migrations against the database when you publish.

Each environment connects to its own database, and you add them one at a time: development first, then staging and production. Use a separate database for each environment, so testing in development or staging can’t change production data.

Connecting the development database

You connect the development database in one of two ways:

When you create the API Backend, choose External Postgres (or API + your Postgres when you create a new project) and fill in Development connection URL.
For an API Backend created with None, open Integrations, go to the Database tab, and click Connect Postgres. Paste the connection URL, add an optional migration URL, and click Connect database.

Once it’s connected, the agent and the API console use this database.

Connecting staging and production

Open Integrations and go to the Database tab. You need the Editor role or higher.
Click Configure staging.
Under Staging Postgres, paste the staging database’s connection URL. If migrations should use a different connection, add it in the Optional migration URL field.
Click Save connection.
Click Configure production and repeat the steps for production.

Configure production appears once staging is saved. Each environment you’ve connected is listed on the Database tab with Credentials configured and a status dot, which turns green when the connection is active.

Replacing a connection URL

To fix a wrong URL or rotate credentials, click Replace URL next to the environment on the Database tab, paste the new connection URL (and migration URL, if you use one), and click Save connection. Saved URLs are never shown again, so you paste both in full; leaving the migration URL blank makes it use the new connection URL. Development switches right away. Staging and production use the new URL the next time you publish to them.

Connection URL and migration URL

Field	What it’s for
Connection URL	What your API uses to read and write data while it runs.
Migration URL	What publishing uses to apply your migrations. If you leave it blank, it uses the connection URL.

Add a migration URL when your provider gives you separate connection strings, for example a pooled one for your app and a direct one for schema changes.

When you save a connection, Draftbit checks that the URL is a Postgres URL with a hostname. It doesn’t connect to the database at that point, so a wrong password or a blocked network shows up later, when your API, the console, or a publish tries to connect.

Postgres console

When an API Backend uses External Postgres, the Database tab also has a console for the development database. You need the Editor role or higher.

Tab	What it does
Tables	Lists your tables and how many columns each has. Select one to browse its first 100 rows.
SQL	Run SQL against the development database and see the results.

Click Refresh schema after the agent adds or changes tables, so the list catches up. If the database has no tables yet, ask the agent to define a schema and run the migrations.

In SQL, a query that could change data or schema needs a second click: the button changes to Run destructive query?, and you click it again to run it. Results show up to 500 rows, and a query that runs longer than 15 seconds is stopped.

The console connects through your API’s own Postgres driver. If it says the postgres driver isn’t installed, ask the agent to set up Drizzle with postgres.js for your database.

Limits

The console only works with the development database. To look at staging or production data, use your database provider’s tools.
You can’t switch an API Backend from External Postgres to D1 or Supabase, or the other way around, automatically.

API keys

Requests to your API need an active key in the x-api-key header. An Authorization: Bearer header with the key also works. Keys are scoped to one environment.

Draftbit creates a Development key for you, and publishing to staging or production creates a key for that environment if it doesn’t have one. That means a published API is protected from the start.

Manage keys in Publishing, on the API tab:

Create Key makes a new key for the environment you choose. Copy it when it appears. You can reveal it again later from the key list.
Copy key copies a key.
Rotate key revokes a key and issues a replacement.
Revoke key turns a key off.

Changes to the development key apply right away. Changes to staging and production keys apply the next time you publish to that environment. If an environment has no active keys, its API accepts all requests.

Publishing

Your API runs in three environments:

Environment	Where it runs
Development	Your sandbox. It restarts as you build, and it’s what the API console calls.
Staging	A deployed version with its own stable URL.
Production	A deployed version with its own stable URL.

To deploy, click Publish in the top bar, then Publish in the API row. Name the version, choose Staging or Production, and start the publish. Publishing runs your database migrations against that environment’s database first.

After a publish, the API tab shows the environment’s URL, which you can copy, and its version. See Publishing for more about versions.

Custom domains

You can serve your staging or production API from a domain you own, such as api.myapp.com. Custom domains are part of the paid plans.

On the API tab, click Add custom domain on the Production or Staging card.
Enter your domain and click Save.
Add the CNAME and TXT records shown to your domain’s DNS. The CNAME points your domain to Draftbit, and the TXT lets Draftbit issue its SSL certificate.
Once DNS and SSL show Verified, click Verify DNS records. Your domain starts serving the environment’s latest publish after the first successful check.

DNS changes can take a few minutes or several hours. Domains left unverified for 7 days are removed. Your API’s draftbit.dev URL keeps working alongside the custom domain. Unlike web apps, API domains don’t get a www redirect, so add the exact hostname your clients call.

The card then shows your domain. To disconnect it, click Manage on that card, then Remove domain. The same plan change rules as web custom domains apply.

When a publish stops at the database

Publishing checks that the environment’s database is ready before it deploys anything. If it isn’t, the publish stops with one of these messages (shown here for staging):

Message	What to do
`staging external Postgres target is not configured.`	You haven’t connected a staging database yet. Click Configure staging on the Database tab, save the connection, and publish again. See External Postgres.
`staging D1 target is not ready.`	Draftbit couldn’t create or reach the D1 database for that environment. On the Database tab, pick the environment. If it shows Retry provisioning, click it, then publish again.

If your migrations fail against an external database, check the migration URL (or the connection URL, if you didn’t set one) and that your database allows connections from the internet.

Connecting your apps

Apps in the same project can use your API Backend:

When you add a mobile app, web app, or website to a project that already has an API Backend, setup asks which backend to use. If there’s only one, it’s picked for you.
When you create a project with D1 or External Postgres, the new app is connected automatically.

Connecting adds two development environment variables to the app, one for the API’s URL and one for its development key. Their names start with the app’s prefix, for example VITE_API_URL and VITE_API_KEY for a web app, EXPO_PUBLIC_ for a mobile app, or PUBLIC_ for a website. You’ll find them in Settings. Set the staging and production values yourself when you’re ready to publish.

The agent in each app knows about the others. The backend’s agent knows which apps will call it, and your app’s agent can read the backend’s API.

While you build, the agent can also work with the other apps’ previews. It can check whether another app is running, read its preview logs, and use its development URL and development API key to connect the two. If that app isn’t running, the agent can start it, within your plan’s limits. When the agent changes another app’s code, it refreshes that app’s preview so the change shows up.