Getting Started

Integrating with Magic Core takes three things: a base URL, a token, and knowledge of which service owns the route you’re calling.

1. Pick your base URL

Production sits behind nginx → gateway, so every service shares one origin and is routed by path prefix. Local development runs each service on its own port with no proxy.

Environment	platform-api (CRUD)	agent-service (AI / streaming)	relay (OpenAI-compatible `/v1`)
Local dev	`http://localhost:3111`	`http://localhost:3112`	`http://localhost:3113`
Production (one origin)	`https://api.magic-resume.cn`	`https://api.magic-resume.cn`	`https://api.magic-resume.cn`

Most routes are mounted under /api — a resume list is GET {platform}/api/resumes/mine, a chat stream is POST {agent}/api/chat. Relay is the exception: its OpenAI-compatible surface lives at /v1 (e.g. POST /v1/chat/completions). Keeper (:3114) is an internal worker + admin service you won’t call directly.

2. Get a token

Programmatic integrations authenticate with a Personal Access Token (PAT) — a string that starts with mr_pat_. You create one from your account, then send it as a Bearer token:


Authorization: Bearer mr_pat_xxxxxxxxxxxxxxxxxxxxxxxx

Full details — how to mint one, scopes, expiry, revocation — are in Authentication.

Relay’s OpenAI-compatible /v1 is the exception: it authenticates with relay keys (mr_rk_…), not PATs. Point an OpenAI client at /v1 with a relay key as the API key.

3. Make your first call

Confirm the service is up


curl http://localhost:3112/api/health
# Readiness (DB + Redis):
# { "status": "ok", "info": { "database": { "status": "up" }, "redis": { "status": "up" } }, "details": { … } }

There are also /api/health/live (liveness only, no deps — for restart probes) and /api/health/ready (readiness, checks DB + Redis) probes.

Call a guarded endpoint with your PAT


curl http://localhost:3111/api/resumes/mine \
  -H "Authorization: Bearer mr_pat_xxx"

Read the envelope

platform-api wraps every success in { code, data, message, timestamp }. Pull your payload from data:


{
  "code": 200,
  "data": [{ "id": "clx...", "title": "Frontend Resume" }],
  "message": "success",
  "timestamp": "2026-06-19T08:00:00.000Z"
}

What can I do with the API?

Manage resumes & versions Mint & manage tokens Stream an AI chat Run analyze / rewrite / research Mock interview (REST + realtime)Generate & parse PDFs

All services share one Postgres database but only platform-api runs migrations on boot. If you self-host, never run migrations from another app — it would race the platform-api migration on shared Postgres.