Sign In

Getting Started

Five minutes from zero to a working API call.

Credentials at a glance

Signing in returns a session JWT — that's your account-level credential, used to manage agents, projects, keys, and OAuth2 clients. Agent and project API keys are separate, minted from the JWT, and used for runtime calls. See account & platform for the full JWT lifecycle.

Credential Prefix Used for
Session JWT (Bearer) Account/project/agent management
Agent API key jg_a_* Runtime calls as one agent
Project API key jg_p_* Runtime calls into a project, with optional X-USER-ID

1. Sign up

Visit juglans.ai and click Sign in with Google. The first sign-in creates your account; subsequent ones drop you back into the app.

2. Pick your scope: agent or project?

If you are building one agent for yourself or your team — pick agent scope. You'll get an agent with memory, an LLM, an optional wallet, and an MCP URL you can paste into Claude Code, Cursor, or Codex.

If you are a company embedding Juglans into your product — pick project scope. A project lets you serve your own end-users with passthrough identity (X-USER-ID), invite collaborators, and configure webhooks.

You can do both. Most people start with an agent.

3. Create your first agent

Click New agent in the sidebar, give it a name, and confirm. Each agent is auto-provisioned with:

  • A persistent memory store (with a persona key the agent reads on session start)
  • An LLM endpoint (proxied through Juglans, so you don't need to BYO key)
  • An optional EVM + Solana wallet (created on demand)
  • A hosted MCP endpoint at POST /mcp
  • A per-agent API key with prefix jg_a_*

The API key is shown once in the create dialog — copy it. To use it:

curl https://api.juglans.ai/api/me \
  -H "Authorization: Bearer jg_a_3f8a9c1..."

4. Or create a project

Click New project in the sidebar. A project is a many-to-many container that groups agents, humans, and end-users.

Project configuration is split across three tabs in the sidebar — pick the one that matches what you're doing:

  • Members — Add agents to the project, invite human collaborators.
  • API (the developer center) — Five sub-tabs:
    • Quickstart — onboarding cards + 30-second curl
    • API keys — Mint, list, revoke jg_p_* keys
    • Embed — Configure the chat widget that drops into your site
    • Webhooks & users — Outbound webhook URL + signing secret + rate limit; visible end-users
    • Reference — Auth modes, endpoint table, SDK snippets
  • Settings — Project name, description, danger zone.

5. Project quickstart (programmatic)

The same flow as the UI, hit directly. Replace tokens and ids as you go; each step's response feeds the next.

1. Sign in to get a JWT. (Step 1 above, in API form. Send the Google id_token; you get back access_token.)

curl https://api.juglans.ai/api/auth/login/google \
  -H "Content-Type: application/json" \
  -d '{"id_token": "<google-id-token>"}'

Response includes access_token, refresh_token, expires_in, account. Save the access_token — that's the JWT.

2. Create the project.

curl https://api.juglans.ai/api/projects \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{"name": "Acme Support"}'

Response: {"project": {"id": "...", "owner_account_id": "...", "name": "Acme Support", ...}}. Grab project.id.

3. Mint a project API key.

curl https://api.juglans.ai/api/projects/{project_id}/api-keys \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{"name": "backend-prod"}'

Response: {"api_key": {"id": "...", "name": "backend-prod", "prefix": "jg_p_a1b2c3d", "key": "jg_p_a1b2c3d4..."}}. The plaintext key is returned once — store it now.

4. Add an agent as a project member. The agent must already exist and be owned by you (step 3 above, or via POST /api/agents).

curl https://api.juglans.ai/api/projects/{project_id}/members \
  -H "Authorization: Bearer <jwt>" \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "<agent-uuid>", "role": "member"}'

5. Send your first chat call. Project key in the Authorization header, X-USER-ID to scope the conversation per end-user. Response is SSE.

curl https://api.juglans.ai/api/projects/{project_id}/chat \
  -H "Authorization: Bearer jg_p_a1b2c3d4..." \
  -H "Content-Type: application/json" \
  -H "X-USER-ID: customer-42" \
  -d '{"agent_id": "<agent-uuid>", "message": "hello"}'

The first SSE event carries {"type": "meta", "conversation_id": "..."}. Pass that conversation_id back on subsequent calls to keep the thread.

The X-USER-ID header is what makes project scope special: the same project key, used with different X-USER-ID values, partitions conversations and memory per end-user. You don't need to onboard your end-users to Juglans directly.

Public endpoints (no auth)

A few endpoints don't need any credential:

  • GET /api/prices, GET /api/prices/{symbol} — spot prices
  • GET /api/markets/perps, GET /api/markets/perps/{symbol} — perp markets
  • GET /api/markets/predictions, GET /api/markets/predictions/{id} — prediction markets
  • GET /.well-known/openid-configuration, GET /.well-known/jwks.json — OIDC discovery (Juglans as IdP)

Key prefixes at a glance

Prefix What it is Where to use it
jg_a_* Per-agent key (live) Agent-scope endpoints (/api/me, /api/orders, /mcp, /api/memory, /api/llm/...)
jg_a_test_* Per-agent key (test mode) Same routes, but the agent is sandboxed
jg_p_* Per-project key Project-scope endpoints (/api/projects/{id}/chat, /api/projects/{id}/conversations)

Older docs may reference jw_* keys. Those were the legacy prefix — the API still validates issued ones for backward compat, but new keys all use jg_a_* / jg_p_*.

Where to next