Neo AI API v1

Build integrations with Neo AI

A REST API to connect your apps, CRM, or point-of-sale system with Neo AI: generate text with AI and read data from the services you use, straight from your own system.

Base URLhttps://api.neo.ai.id/api/open/v1

Secure by defaultAPI Keys are stored as hashes and can be limited by scope and expiry. AI provider credentials never leave Neo AI's servers.

One balanceAI usage through the API draws from the same Neo Token balance as the app.

Clear limitsPer-minute limits and monthly quotas follow your plan and are visible on every response.

Quickstart

Choose a plan that includes the API. API access is available on selected plans (see Plans, limits & quotas).
Create an API Key in the Developer API menu of the member area. Pick only the scopes you need, then copy the API Key; it is shown only once.
Send your first request to /account with the Authorizationheader. A 200 response means your integration is ready.

Keep API Keys on your server (environment variables or a secret manager). Never put them in mobile apps, browser JavaScript, or code repositories.

Terminal

curl "https://api.neo.ai.id/api/open/v1/account" \
  -H "Authorization: Bearer neo_live_xxxxxxxxxx_xxxxxxxx…"

Authentication

Every request must include the API Key in the Authorization header using the Bearer scheme. API Keys look like neo_live_ followed by a 10-character identifier and a 40-character secret.

Invalid, revoked, or expired API Keys are rejected with 401 authentication_error.
If your plan no longer includes the API, keys are rejected with 403 permission_error until the plan is reactivated.
Neo AI only stores a fingerprint (hash) of each API Key. If a key is lost, revoke it and create a new one.
All production requests must use HTTPS.

Header

Authorization: Bearer neo_live_ab12cd34ef_<secret-40-chars>
Accept: application/json

Scopes & permissions

Limit each API Key to the permissions its integration needs. Requests to endpoints outside the key's scopes are rejected with 403.

Scope	Grants access to
`account:read`	Read the account profile, plans, Neo Token balance, and usage history.
`ai:generate`	Generate text with AI. Consumes Neo Tokens.
`chat:read`	List Neo Chat bots.
`chat:reply`	Request Neo Chat bot replies for conversations from your own system. Consumes Neo Tokens.
`forms:read`	Read Neo Form forms and their responses.
`legal:read`	Read Neo Legal documents and each party's signing status.
`sites:read`	List Neo Builder websites.
`slides:read`	List Neo Slides presentations.

Plans, limits & quotas

API access follows your active plan. Each plan sets a per-minute limit, a monthly quota, and the number of active API Keys. Quotas reset at the start of each month.

Plan	Per minute	Per month	API Keys
Neo Token Pro	50	1,500	1
Neo Token Bisnis	100	Unlimited	3

Every response includes these headers so your app can adapt its rate:

X-RateLimit-Limit & X-RateLimit-Remaining: limit and remaining requests this minute.
X-Quota-Remaining: remaining quota this month (unless unlimited).
Retry-After: seconds to wait after receiving 429.
X-Request-Id: unique request ID for support.

View & order plans

Response headers

HTTP/1.1 200 OK
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 117
X-Quota-Remaining: 48716
X-Request-Id: req_k3v9x2m1q8w7z5p4a1b2

Errors

Errors are always an error object with a stable type for programmatic checks and a human-readable message (currently in Indonesian, so branch on type rather than message). Internal server or AI provider messages are never exposed.

Status	Type	Meaning
400	`invalid_request_error`	The request is malformed.
401	`authentication_error`	The API Key is missing, invalid, revoked, or expired.
402	`insufficient_tokens`	Not enough Neo Tokens. Top up and retry.
403	`permission_error`	Your plan does not include API access, or the API Key lacks the required scope.
404	`not_found_error`	Endpoint or resource not found (or it doesn't belong to your account).
422	`invalid_request_error`	Invalid parameters. Per-field details are in error.fields.
429	`rate_limit_error`	Per-minute limit exceeded. Wait as indicated by the Retry-After header.
429	`quota_exceeded`	Your plan's monthly request quota is used up.
500	`api_error`	An error on Neo AI's side. Safe to retry; include the request_id when contacting support.
503	`service_unavailable`	The API is under maintenance. Try again shortly.

402Error example

{
  "error": {
    "type": "insufficient_tokens",
    "message": "Saldo Neo Token tidak cukup untuk permintaan ini.",
    "required": 2,
    "balance": 0,
    "request_id": "req_k3v9x2m1q8w7z5p4a1b2"
  }
}

Pagination

List endpoints return data as an array and meta with page information. Use the page and per_page parameters (max 100) and continue while has_more is true.

List shape

{
  "data": [
    "…"
  ],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 128,
    "has_more": true
  }
}

Neo Tokens & billing

Read endpoints don't consume tokens; only the request quota counts. AI endpoints (/ai/generate and bot replies) consume Neo Tokens from the same balance as the app, based on input and output length. The tokens charged are always returned in the response (neo_tokens_charged), and the history is available via Token usage history.

Account

Retrieve account

GET/account

Account profile, active plans, Neo Token balance, and this month's API quota usage. A good first connection test.

Scope account:readNo token cost

curl "https://api.neo.ai.id/api/open/v1/account" \
  -H "Authorization: Bearer $NEO_API_KEY"

200Response

{
  "data": {
    "id": 128,
    "name": "Rina Wulandari",
    "email": "rina@tokorotisenja.com",
    "company_name": "Toko Roti Senja",
    "plans": [
      {
        "name": "Neo Token Bisnis",
        "products": [
          "builder",
          "slides",
          "forms"
        ],
        "ends_at": "2026-12-31T23:59:59+07:00"
      }
    ],
    "tokens": {
      "balance": 18250,
      "plan_balance": 15000,
      "topup_balance": 3250
    },
    "api": {
      "requests_month": 50000,
      "requests_used": 1284,
      "rate_limit_per_minute": 120
    }
  }
}

Token usage history

GET/usage

Neo Token transactions (usage, monthly allowance, top-ups), newest first.

Scope account:readNo token cost

Parameters

fromdatequeryoptional
Start date (YYYY-MM-DD).
todatequeryoptional
End date (YYYY-MM-DD), inclusive.
per_pageintegerqueryoptional
1–100, default 25.
pageintegerqueryoptional
Page number, starting at 1.

curl "https://api.neo.ai.id/api/open/v1/usage" \
  -H "Authorization: Bearer $NEO_API_KEY"

200Response

{
  "data": [
    {
      "id": 90211,
      "type": "usage",
      "amount": -14,
      "balance_after": 18250,
      "description": "Neo AI API — /ai/generate",
      "created_at": "2026-10-11T09:24:51+07:00"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 1,
    "has_more": false
  }
}

AI

Generate text with AI

POST/ai/generate

Generate text from a prompt or conversation: product descriptions, email replies, summaries, content ideas, and more. Processed entirely on Neo AI's servers.

Scope ai:generateConsumes Neo Tokens

Parameters

promptstringbodyoptional
Instruction or question (max 20,000 characters). Required when messages is not sent.
messagesarraybodyoptional
Multi-turn conversation: [{ role: "user" | "assistant", content }]. Must start and end with the user role.
systemstringbodyoptional
Additional instructions for tone, persona, or output format.
max_tokensintegerbodyoptional
Maximum response length, 16–4,000. Default 1,024.

Cost is based on input and output length, using the "API text generation" rate shown on the Tokens & usage page.

curl -X POST "https://api.neo.ai.id/api/open/v1/ai/generate" \
  -H "Authorization: Bearer $NEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "prompt": "Tulis 3 deskripsi singkat untuk roti sourdough keju, nada hangat dan menggugah selera.",
  "system": "Jawab dalam bahasa Indonesia, maksimal 40 kata per deskripsi.",
  "max_tokens": 400
}'

200Response

{
  "data": {
    "id": "gen_k3v9x2m1q8w7z5p4",
    "text": "1. Sourdough keju dengan kulit renyah dan bagian dalam lembut…",
    "usage": {
      "input_tokens": 64,
      "output_tokens": 182,
      "neo_tokens_charged": 3
    }
  }
}

Neo Chat

List bots

GET/chat/bots

All Neo Chat bots in the account.

Scope chat:readNo token cost

Parameters

per_pageintegerqueryoptional
1–100, default 25.
pageintegerqueryoptional
Page number, starting at 1.

curl "https://api.neo.ai.id/api/open/v1/chat/bots" \
  -H "Authorization: Bearer $NEO_API_KEY"

200Response

{
  "data": [
    {
      "id": 12,
      "name": "Senja Bot",
      "business_name": "Toko Roti Senja",
      "language": "id",
      "ai_enabled": true,
      "created_at": "2026-09-02T10:11:00+07:00"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 1,
    "has_more": false
  }
}

Bot reply

POST/chat/bots/{bot}/reply

Get the bot's answer (based on its instructions and knowledge base) for conversations from your own app, such as a POS or CRM. The caller sends the conversation history.

Scope chat:replyConsumes Neo Tokens

Parameters

botintegerpathrequired
Bot ID from List bots.
messagesarraybodyrequired
Up to 30 messages [{ role, content }], starting and ending with a user message.

handoff is true when the bot decides the customer should be handled by a human (per the bot's settings).

curl -X POST "https://api.neo.ai.id/api/open/v1/chat/bots/12/reply" \
  -H "Authorization: Bearer $NEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "messages": [
    {
      "role": "user",
      "content": "Kue ulang tahun 20 cm bisa dipesan untuk besok?"
    }
  ]
}'

200Response

{
  "data": {
    "reply": "Bisa, Kak! Kue 20 cm tersedia rasa coklat & keju mulai Rp185.000. Mau diantar atau ambil di toko?",
    "handoff": false,
    "handoff_reason": null,
    "neo_tokens_charged": 2
  }
}

Neo Form

List forms

GET/forms

Neo Form forms in the account with their response counts.

Scope forms:readNo token cost

Parameters

per_pageintegerqueryoptional
1–100, default 25.
pageintegerqueryoptional
Page number, starting at 1.

curl "https://api.neo.ai.id/api/open/v1/forms" \
  -H "Authorization: Bearer $NEO_API_KEY"

200Response

{
  "data": [
    {
      "id": 31,
      "title": "Pendaftaran Workshop Baking",
      "status": "published",
      "responses_count": 128,
      "url": "https://app.neoai.id/f/workshop-baking",
      "published_at": "2026-10-01T08:00:00+07:00",
      "created_at": "2026-09-28T13:40:00+07:00"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 1,
    "has_more": false
  }
}

Form responses

GET/forms/{form}/responses

Responses submitted to a form, newest first. Use since for periodic syncing to your system.

Scope forms:readNo token cost

Parameters

formintegerpathrequired
Form ID.
sincedatetimequeryoptional
Only responses since this time (ISO 8601).
per_pageintegerqueryoptional
1–100, default 25.

curl "https://api.neo.ai.id/api/open/v1/forms/31/responses" \
  -H "Authorization: Bearer $NEO_API_KEY"

200Response

{
  "data": [
    {
      "id": 5521,
      "number": 128,
      "created_at": "2026-10-11T08:12:09+07:00",
      "answers": [
        {
          "question_id": "q1",
          "question": "Nama lengkap",
          "value": "Dewi Lestari"
        },
        {
          "question_id": "q2",
          "question": "Pilih sesi",
          "value": "Siang"
        }
      ]
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 1,
    "has_more": false
  }
}

Neo Legal

List documents

GET/legal/documents

Neo Legal documents in the account with a signing summary. Filter by status to track documents being signed.

Scope legal:readNo token cost

Parameters

statusstringqueryoptional
draft, final, signing (in progress), or signed (completed).
per_pageintegerqueryoptional
1–100, default 25.
pageintegerqueryoptional
Page number, starting at 1.

curl "https://api.neo.ai.id/api/open/v1/legal/documents" \
  -H "Authorization: Bearer $NEO_API_KEY"

200Response

{
  "data": [
    {
      "id": 58,
      "title": "Perjanjian Kerja Sama Distribusi",
      "number": "PKS/RS/X/2026/014",
      "category": "bisnis",
      "status": "signing",
      "signers": {
        "total": 2,
        "signed": 1
      },
      "sent_at": "2026-10-10T14:02:00+07:00",
      "completed_at": null,
      "updated_at": "2026-10-11T09:15:00+07:00"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 1,
    "has_more": false
  }
}

Document & signing status

GET/legal/documents/{document}

One document's details and each signer's status (pending, viewed, signed, declined), plus an authenticity verification link once completed.

Scope legal:readNo token cost

Parameters

documentintegerpathrequired
Document ID from List documents.

verification_url is filled once all parties have signed; share it with third parties to confirm the PDF hasn't been altered.

curl "https://api.neo.ai.id/api/open/v1/legal/documents/58" \
  -H "Authorization: Bearer $NEO_API_KEY"

200Response

{
  "data": {
    "id": 58,
    "title": "Perjanjian Kerja Sama Distribusi",
    "number": "PKS/RS/X/2026/014",
    "category": "bisnis",
    "status": "signing",
    "language": "id",
    "signers": [
      {
        "role": "Pihak Pertama",
        "name": "Rina Wulandari",
        "organization": "Toko Roti Senja",
        "status": "signed",
        "viewed_at": "2026-10-10T14:05:00+07:00",
        "signed_at": "2026-10-10T14:07:12+07:00"
      },
      {
        "role": "Pihak Kedua",
        "name": "Budi Santoso",
        "organization": "CV Sumber Rejeki",
        "status": "pending",
        "viewed_at": null,
        "signed_at": null
      }
    ],
    "verification_url": null,
    "sent_at": "2026-10-10T14:02:00+07:00",
    "completed_at": null,
    "created_at": "2026-10-09T10:00:00+07:00",
    "updated_at": "2026-10-11T09:15:00+07:00"
  }
}

Neo Builder

List websites

GET/sites

Neo Builder websites in the account with their public URLs.

Scope sites:readNo token cost

Parameters

per_pageintegerqueryoptional
1–100, default 25.

curl "https://api.neo.ai.id/api/open/v1/sites" \
  -H "Authorization: Bearer $NEO_API_KEY"

200Response

{
  "data": [
    {
      "id": 7,
      "name": "Toko Roti Senja",
      "status": "published",
      "url": "https://tokorotisenja.com",
      "published_at": "2026-09-20T10:00:00+07:00",
      "updated_at": "2026-10-10T16:30:00+07:00"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 1,
    "has_more": false
  }
}

Neo Slides

List presentations

GET/slides

Neo Slides presentations in the account, including share links when published.

Scope slides:readNo token cost

Parameters

per_pageintegerqueryoptional
1–100, default 25.

curl "https://api.neo.ai.id/api/open/v1/slides" \
  -H "Authorization: Bearer $NEO_API_KEY"

200Response

{
  "data": [
    {
      "id": 44,
      "title": "Strategi Pemasaran Q4",
      "status": "ready",
      "slides": 8,
      "share_url": "https://api.neoai.id/s/9f2c…",
      "updated_at": "2026-10-09T19:05:00+07:00"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 25,
    "total": 1,
    "has_more": false
  }
}

Security best practices

Keep it server-sideCall the API from your backend. Keys in browsers or mobile apps can be stolen.

Least privilegeOne API Key per integration with only the scopes it needs.

Rotate regularlySet expiry dates and replace keys when staff leave.

Revoke if leakedRevoked keys are rejected on every subsequent request.

Changelog

Oct 2026
v1 released
Account & usage, AI text generation, and data endpoints for active Neo AI services.

Breaking changes will ship as a new version (e.g. /v2) with advance notice.