Build your first API

Write a typed Acore endpoint, build its contract, run it locally and call it with curl.

Write a small API in Acore, build its contract and call the running endpoint. If you already have a service, follow the FastAPI or Go guide instead; those keep your existing backend.

A request to GET /hello runs the hello action and returns a typed Greeting

Prerequisites

Axiom CLI 0.149.1. This walkthrough is checked on macOS arm64.
Port 8081 free. The example has no database or external providers.
An empty directory named hello-api. Run every command from it.

The finished files are also in the repository. To use them instead of typing, run git clone --depth 1 https://github.com/AxiomCore/AxiomCore.git and cd AxiomCore/examples/documentation/hello-api.

1. Define the project and endpoint

AxiomDeps.toml

type = "backend"
targets = ["server"]
audiences = ["web"]

main.acore

project(id: "docs.hello", version: "1.0.0")
variant default(include: ["*"])
model Greeting { message: String }
action hello(kind: ActionKind.query, output: Models.Greeting) {
  managed { return {message: "Hello from Acore"} }
}
endpoint hello(method: GET, path: "/hello") {
  handle(action: Actions.hello) 
  response(type: Models.Greeting)
}

The manifest marks the directory as a backend for the server target. The action returns a typed Greeting, and handle connects the public endpoint to that action. Request validation and response types belong to the contract.

2. Build and inspect

Terminal 1: hello-api

axiom check main.acore
axiom build main.acore --out backend.axiom

Expected output

Valid backend contract: main.acore
Built backend contract: backend.axiom

--out exports the contract to a known path. The build also writes backend.server.json, the private server plan. To browse the contract, run axiom inspect backend.axiom in an interactive terminal (Tab switches views, / searches, q quits). For plain text output, run axiom inspect overview backend.axiom.

3. Create a deployment configuration

Terminal 1: hello-api

axiom server deployment backend.axiom backend.server.json --output deployment.json

The server plan and deployment configuration stay on the backend; clients get only the public contract. This scaffold grants no providers, and the hello action needs none. Review providers, authentication and grants before you add real effects.

4. Run and verify

Terminal 1: hello-api

axiom run main.acore --deployment deployment.json --port 8081

In a second terminal:

Terminal 2

curl -fsS http://127.0.0.1:8081/hello

Expected response

{"message":"Hello from Acore"}

This is the real action, not a mock. The endpoint is public and returns a constant, so add authentication before you expose protected data.

Troubleshooting

Symptom	Fix
`axiom check` prints an error	The message gives a code and the declaration, such as `action.hello`. Compare that declaration with the listing above.
`curl` cannot connect	Check that Terminal 1 is still running and that both use port 8081.
Port 8081 is in use	Pick another `--port` and use it in the `curl` URL.
`axiom inspect backend.axiom` fails with `Resource temporarily unavailable`	That view needs an interactive terminal. Use `axiom inspect overview backend.axiom`.

Cleanup

Stop the server with Ctrl-C. Delete the hello-api directory to remove backend.axiom, backend.server.json, deployment.json and the .axiom directory the build created.

Extend the API

Need	Continue with
Persist records	Run your first app and Migrations and persistence
Add validation and typed failures	Managed logic and Backend declarations
Put an existing framework in front	Deployment targets
Test without real effects	Server simulation
Release the service	Build a backend and Release a backend

A build does not deploy a backend. Native releases, Linux containers and local Workers have different support limits; see Deployment targets.

Build your first API

Prerequisites

1. Define the project and endpoint

2. Build and inspect

3. Create a deployment configuration

4. Run and verify

Troubleshooting

Cleanup

Extend the API

Next steps

On this page