Developer documentation

Build with the O My Syria interfaces available today

Use the implemented REST contract and restricted web Widget safely. This documentation is explicit about what is available now and what remains planned.

POST /v1/answers

Quick start

Confirm the local API in one request

The public system ping is the smallest safe request for verifying that your local gateway and required dependencies are ready.

1Start the local API and its required dependencies.
2Send the request from your terminal.
3Expect a 200 response with the standard data envelope.

Public readiness requestPOST /v1/answers

curl --request POST "https://omysyria.com/v1/answers" \
  --header "Content-Type: application/json" \
  --header "X-AHS-API-Key: $AHS_SERVER_KEY" \
  --data '{
    "message_id": "msg-001",
    "question": "كيف أسحب رصيدي من المحفظة؟",
    "language": "ar"
  }'

Authentication boundaries

Choose credentials by endpoint, not by convenience

Every operation in the reference declares its actual security scheme. Credentials remain scoped to one purpose and must never be exchanged for another.

Implemented

Server secret API key

Trusted backends call POST /v1/answers with X-AHS-API-Key and no browser Origin. An optional exact IP allowlist can restrict the source. Never place this secret in browser or mobile code.

Implemented

Management session

Dashboard and management routes use the secure ahs_session cookie. State-changing browser requests also require the paired X-CSRF-Token header. These routes are not a server-key API.

Implemented

Publishable Widget key

Widget routes accept X-AHS-Publishable-Key only from an allowed browser origin. Conversation operations also use a short-lived X-AHS-Conversation-Token. A publishable key is restricted, browser-visible, and not an administrative secret.

Trusted backend storage only

Never send the server key or conversation reference to browser code, mobile apps, or logs. Treat conversation_ref as opaque metadata and do not place customer questions or O My Syria answers in operational logs.

Base URLsHTTPS Encrypted

Base URLs & Environments

Use the target environment URL when sending requests from your backend.

Production EnvironmentProduction

https://omysyria.com

Requires ahs_sk_live_... server key.

Test & Local EnvironmentTest / Dev

http://localhost:8080

For local testing and sandbox workflows with ahs_sk_test_... keys.

REST EndpointsJSON over HTTP

Available Messages Endpoints

These are the exact endpoints used to connect apps (like TakeCar) to send customer questions and receive grounded AI responses.

POST /v1/answersPrimary

Send Message & Get Answer

Send customer inquiry and receive grounded AI answers with multi-turn conversation memory.

DELETE /v1/server-conversationsLifecycle

End / Delete Conversation

Delete retained conversation history by opaque reference when session ends.

Code Integration & Ready SDK Helpers

Select scenario and language to copy ready integration code or full client wrapper.

curl --request POST "https://omysyria.com/v1/answers" \
  --header "Content-Type: application/json" \
  --header "X-AHS-API-Key: ahs_sk_live_••••••••••••" \
  --data '{
    "message_id": "takecar-msg-101",
    "question": "كيف أسحب رصيدي من المحفظة؟",
    "language": "ar"
  }'

Response Envelope 200 OK200 OK

{
  "data": {
    "status": "grounded",
    "answer": "يمكنك سحب الرصيد المتاح من خلال فتح صفحة المحفظة في تطبيق TakeCar، ثم اختيار طلب سحب وإدخال البيانات البنكية المطلوبة.",
    "conversation_ref": "ahs_conv_live_9f83a27e01b44298a0c6d9124e8371b29a8f",
    "message_id": "takecar-msg-101",
    "handoff_suggested": false,
    "citations": [
      {
        "citation_id": "cite_01",
        "source_filename": "takecar-driver-operations.md"
      }
    ]
  }
}

Conversation Flow & Architecture

How multi-turn memory works across requests using opaque conversation references.

Initial Turn

Send question and message_id. O My Syria returns answer and conversation_ref.

Store Reference

Your server stores conversation_ref alongside user support session.

Follow-up Turns

Send next question with conversation_ref and new message_id to maintain dialogue context.

Handoff or End

If handoff_suggested is true, escalate to human agent; call DELETE when session ends.

Detailed Parameter Specifications

Comprehensive field constraints, regular expressions, and payload limits.

1. Request Headers

Header	Type & Status	Description & Constraints
X-AHS-API-Key	Required	Server secret API key (ahs_sk_live_... or ahs_sk_test_...). Never expose to client applications.
Content-Type	application/json	Payload encoding format must be application/json.
X-AHS-Conversation-Ref	Required for DELETE only	Passed in DELETE /v1/server-conversations to specify conversation to destroy.

2. Request Body (POST /v1/answers)

Field	Type	Status	Description & Constraints
question	string	Required	The text of customer message. Max 8KB UTF-8 text.
message_id	string	Recommended	Unique client message ID (regex: ^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$, max 128 chars) for idempotency and ordering.
conversation_ref	string	Optional	Opaque conversation reference (ahs_conv_live_...) returned from previous turn to resume dialogue memory.
language	string	Optional	Language code ("ar" or "en"). Defaults to "ar".

3. Response Fields (data object)

Field	Type	Explanation & Possible Values
status	string	groundedinsufficient_contextout_of_scopesafety_flagged Grounded generation status code.
answer	string	The generated grounded answer text in natural Arabic/English.
conversation_ref	string	The opaque conversation reference to store and send in follow-up turns.
message_id	string	The client message ID matching the request.
handoff_suggested	boolean	True if human support escalation is recommended.
citations	array	List of source files referenced in the response.

Error Codes & Responses

All error responses follow the standard ErrorEnvelope format.

401 Unauthorized

invalid_api_key

Server API key is missing, invalid, or revoked.

422 Unprocessable

invalid_input

Validation failed on question length or payload format.

422 Unprocessable

invalid_message_id

Invalid message_id format (must match regex).

404 Not Found

conversation_not_found

Conversation reference expired (30d) or deleted.

409 Conflict

request_in_progress

Message is currently generating. Read Retry-After header.

409 Conflict

idempotency_conflict

Same message_id was reused with different payload.

429 Rate Limited

rate_limited

Rate limit exceeded (200 req/min per server key).

503 Unavailable

grounded_answer_unavailable

Grounded generation is temporarily unavailable.