التذاكر

Create tickets, read their status and add comments (REST API v1).

إنشاء تذكرة

POST /api/v1/tickets

Creates a ticket in the tenant bound to the API key. Send an Idempotency-Key header so retries don’t create duplicates: a repeated key returns the original result with action: deduplicated.

المصادقة: مفتاح API: Authorization: Bearer nhk.<keyid>.<secret>, أو مفتاح API في X-NH-API-Key

المعاملات

الاسم	الموضع	النوع	إلزامي	الوصف
`Idempotency-Key`	ترويسة	string	لا	Unique key per logical operation (UUID recommended). A retry with the same key returns the first result.

محتوى الطلب

application/json

الاسم	النوع	إلزامي	الوصف
`subject`	string	لا	Ticket title. Required (alias: `summary`).
`summary`	string	لا	مُهمل Alias of `subject`.
`description`	string	لا	Body text (alias: `body`).
`priority`	string	لا	Priority name. The tenant’s priority scheme may define more values.
`category`	string	لا	Category hint used by routing.
`issuetype`	string	لا	Issue-type override, for example `IT-INC` or `IT-SR`.
`country`	string	لا	ISO 3166-1 alpha-2 country, if your tenant routes by country.
`sender_email`	string (email)	لا	Requester. Defaults to the key’s contact.
`sender_name`	string	لا
`sender_phone`	string	لا
`company`	string	لا
`external_id`	string	لا	Your system’s id, kept for correlation.
`tags`	array<string>	لا
`attachments`	array<object>	لا	Attachments by reference (URL). Binary upload is not part of v1.
`attachments[].name`	string	نعم
`attachments[].url`	string (uri)	لا
`attachments[].size`	integer	لا
`attachments[].mime`	string	لا

{
  "subject": "Payment gateway returns HTTP 502",
  "description": "Checkout fails for all EU customers since 09:12 UTC.",
  "priority": "High",
  "category": "Application",
  "sender_email": "[email protected]",
  "sender_name": "ACME On-call",
  "external_id": "INC-88231",
  "tags": [
    "checkout",
    "eu-west"
  ]
}

الاستجابات

الحالة	الوصف
`200`	Ticket created (or deduplicated by `Idempotency-Key`).
`400`	Invalid request.
`401`	API key missing, invalid or revoked.
`403`	Key disabled or missing the required scope.
`429`	Rate limit exceeded for this API key.
`500`	Unexpected server error. Retry with the same `Idempotency-Key`.

مثال 200

{
  "ok": true,
  "ticket_key": "ACME-1042",
  "ingestion_id": "ing_7f3c2a91",
  "action": "created",
  "status_url": "/api/v1/tickets/ACME-1042",
  "skipped": null,
  "backend_status": null,
  "backend_error": null,
  "error": null,
  "post_routing": null
}

مثال باستخدام curl

curl -X POST "https://exocortex-api.ai-exo-cortex.com/api/v1/tickets" \
  -H "Authorization: Bearer $EXO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  --data '{"subject":"Payment gateway returns HTTP 502","description":"Checkout fails for all EU customers since 09:12 UTC.","priority":"High","category":"Application","sender_email":"[email protected]","sender_name":"ACME On-call","external_id":"INC-88231","tags":["checkout","eu-west"]}'

عرض تذكرة

GET /api/v1/tickets/{key}

Returns the current status of a ticket in the API key’s tenant. Tickets of other tenants return 404.

المصادقة: مفتاح API: Authorization: Bearer nhk.<keyid>.<secret>, أو مفتاح API في X-NH-API-Key

المعاملات

الاسم	الموضع	النوع	إلزامي	الوصف
`key`	المسار	string	نعم	Ticket key.

الاستجابات

الحالة	الوصف
`200`	Ticket found.
`401`	API key missing, invalid or revoked.
`403`	Key disabled or missing the required scope.
`404`	Ticket not found in the API key’s tenant.
`429`	Rate limit exceeded for this API key.
`500`	Unexpected server error. Retry with the same `Idempotency-Key`.

مثال 200

{
  "ok": true,
  "ticket": {
    "key": "ACME-1042",
    "summary": "Payment gateway returns HTTP 502",
    "status": "In Progress",
    "priority": "High",
    "assignee": "Jane Doe",
    "created": "2026-11-01T09:14:05.000Z",
    "updated": "2026-11-01T09:31:47.000Z"
  }
}

مثال باستخدام curl

curl -X GET "https://exocortex-api.ai-exo-cortex.com/api/v1/tickets/ACME-1042" \
  -H "Authorization: Bearer $EXO_API_KEY"

إضافة تعليق

POST /api/v1/tickets/{key}/comment

المصادقة: مفتاح API: Authorization: Bearer nhk.<keyid>.<secret>, أو مفتاح API في X-NH-API-Key

المعاملات

الاسم	الموضع	النوع	إلزامي	الوصف
`key`	المسار	string	نعم	Ticket key.
`Idempotency-Key`	ترويسة	string	لا	Unique key per logical operation (UUID recommended). A retry with the same key returns the first result.

محتوى الطلب

application/json

الاسم	النوع	إلزامي	الوصف
`comment`	string	لا	Comment text. Required (alias: `text`).
`text`	string	لا	مُهمل Alias of `comment`.
`sender_email`	string (email)	لا
`sender_name`	string	لا

{
  "comment": "Rollback of release 4.18.2 completed; error rate back to baseline.",
  "sender_email": "[email protected]"
}

الاستجابات

الحالة	الوصف
`200`	Comment accepted.
`400`	Invalid request.
`401`	API key missing, invalid or revoked.
`403`	Key disabled or missing the required scope.
`404`	Ticket not found in the API key’s tenant.
`429`	Rate limit exceeded for this API key.
`500`	Unexpected server error. Retry with the same `Idempotency-Key`.

مثال 200

{
  "ok": true,
  "ticket_key": "ACME-1042",
  "ingestion_id": "ing_91be04d2"
}

مثال باستخدام curl

curl -X POST "https://exocortex-api.ai-exo-cortex.com/api/v1/tickets/ACME-1042/comment" \
  -H "Authorization: Bearer $EXO_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  --data '{"comment":"Rollback of release 4.18.2 completed; error rate back to baseline.","sender_email":"[email protected]"}'

صفحة مُنشأة من مواصفة OpenAPI لواجهة التكامل، الإصدار 1.1.0.