Ask Nora a question

POSThttps://api.norreach.app/v1/nora/ask

Asks Nora — the workspace's AI colleague — a question and returns her answer, with the real data she shows when the question is about it (replies, numbers, connections, people, post engagement, what works in your ads) — cut to what this key's scopes may read (data_needs_scope names the scope otherwise). Nora answers from the workspace's data, the way she does in the app. Asking NEVER starts work, sends, approves, builds or changes anything; to have Nora do something, give her a task (POST /nora/runs). Asked to make or find ads, she says she makes them inside a plan (ads_by_plan: true; POST /briefs). The answer follows Accept-Language. Up to 10 questions a minute per key and 200 an hour per workspace.

nora:askRole must allow: nora.askOperation id: ask_nora

POST/nora/ask

curl -X POST "https://api.norreach.app/v1/nora/ask" \
  -H "Authorization: Bearer $NORREACH_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "question": "How many people replied this week?"
}'

Ask Nora a question

{
  "object": "nora_answer",
  "question": "How many people replied this week?",
  "answer": "Nine people wrote back this week — six on email and three on WhatsApp. Two of them asked for a call.",
  "ads_by_plan": false,
  "data": {
    "type": "replies",
    "items": [
      {
        "thread_id": "1f2e3d4c-5b6a-4978-8a9b-0c1d2e3f4a5b",
        "name": "Anna Berg",
        "company": "Nordic Dental",
        "channel": "email",
        "subject": "Re: winter staffing",
        "body": "Sounds good — can you call me Thursday?",
        "time_ago": "2 h ago",
        "unread": true
      }
    ]
  },
  "data_needs_scope": null
}

Authorizations

Authorizationstringheaderrequired

Bearer authentication: send Authorization: Bearer <key>, with an API key or an OAuth access token. The key needs the scope nora:ask. API keys and scopes

Headers

Idempotency-Keystringheader

Any unique string (≤ 255). The same key with the same request returns the first answer for 24 hours.

Body

application/json

questionstringrequired

The question, in plain words.

Response

200application/json— Ask Nora a question

object"nora_answer"required

questionstringrequired

answerstringrequired

Nora's answer, in the language of Accept-Language.

ads_by_planbooleanrequired

true when the question asked Nora to make or find ads: she makes ads only inside a plan (POST /briefs).

dataobject | nullrequired

The real data Nora showed with her answer (the same view the phone app draws: replies, numbers, connections, people, post engagement, what works, or a page to open).

data_needs_scopestring | nullrequired

When Nora showed data this key may not read: the scope it would need.

Errors

Errors are application/problem+json with a stable code.

Status	Code	Meaning
400	`bad_request`	The request couldn't be read.
400	`unknown_field`	The request has a field this operation doesn't know.
401	`unauthorized`	A valid API key is required.
403	`insufficient_scope`	This API key doesn't have the scope this operation needs.
403	`feature_not_enabled`	The API isn't switched on for this workspace.
403	`role_forbidden`	The key's creator's role can't do this.
409	`idempotency_in_progress`	A request with this Idempotency-Key is still running.
413	`too_large`	The request body is too large.
422	`validation_failed`	The request has invalid fields.
422	`idempotency_mismatch`	This Idempotency-Key was used with a different request.
429	`rate_limited`	Too many requests. Slow down and try again.
500	`server_error`	Something went wrong on our side.
503	`unavailable`	The API isn't available right now. Try again shortly.

POST/nora/ask

curl -X POST "https://api.norreach.app/v1/nora/ask" \
  -H "Authorization: Bearer $NORREACH_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "question": "How many people replied this week?"
}'

Ask Nora a question

{
  "object": "nora_answer",
  "question": "How many people replied this week?",
  "answer": "Nine people wrote back this week — six on email and three on WhatsApp. Two of them asked for a call.",
  "ads_by_plan": false,
  "data": {
    "type": "replies",
    "items": [
      {
        "thread_id": "1f2e3d4c-5b6a-4978-8a9b-0c1d2e3f4a5b",
        "name": "Anna Berg",
        "company": "Nordic Dental",
        "channel": "email",
        "subject": "Re: winter staffing",
        "body": "Sounds good — can you call me Thursday?",
        "time_ago": "2 h ago",
        "unread": true
      }
    ]
  },
  "data_needs_scope": null
}