Skip to main content

REST API

Overview​

Arcanna provides a REST API to send data to Arcanna, get decisions and provide feedback, in order to improve the AI models. This API can be used with all jobs configured with External REST API or Third party input. The Swagger describing all endpoints can be found at http://<your-arcanna.ai-url>:9666/docs.

Authentication​

Authentication is done using the x-arcanna-api-key header and the token generated from: Arcanna.ai UI -> Profile (top right) -> API Keys.

Endpoints​

Event Ingestion​

POST /api/v1/events/​

  • Send a JSON event payload for Arcanna to provide a decision on. Arcanna will generate a new internal ID for the event.
Example curl command:​
curl -X POST "https://api.arcanna.ai/api/v1/events/" \
-H "Content-Type: application/json" \
-H "x-arcanna-api-key: your-api-key-here" \
-d '{
  "job_id": 123,
  "raw_body": {
    "example_field": "example_value"
  }
}'
Expected Response:​

Status Code: 201 Created

{
  "event_id": "15427818711674",
  "job_id": 123,
  "ingest_timestamp": "2024-02-15T11:50:13.781871Z",
  "status": "pending_inference",
  "error_message": null
}

POST /api/v1/events/{event_id}​

  • Send a JSON event payload for Arcanna to provide a decision on. Arcanna will use the provided ID as the event internal ID.
Example curl command:​
curl -X POST "https://api.arcanna.ai/api/v1/events/15427818711674" \
-H "Content-Type: application/json" \
-H "x-arcanna-api-key: your-api-key-here" \
-d '{
  "job_id": 123,
  "raw_body": {
    "example_field": "example_value"
  }
}'
Expected Response:​

Status Code: 201 Created

{
  "event_id": "15427818711674",
  "job_id": 123,
  "ingest_timestamp": "2024-02-15T11:50:13.781871Z",
  "status": "pending_inference",
  "error_message": null
}

Event Retrieval​

GET /api/v1/events/{job_id}/{event_id}​

  • Get decision details of an event previously ingested in Arcanna.
Example curl command:​
curl -X GET "https://api.arcanna.ai/api/v1/events/123/15427818711674" \
-H "x-arcanna-api-key: your-api-key-here"
Expected Response:​

Status Code: 200 OK

{
  "event_id": "15427818711674",
  "ingest_timestamp": "2024-02-15T11:50:13.781871Z",
  "status": "OK",
  "result": "drop_alert",
  "result_label": "Drop",
  "bucket_state": "new",
  "outlier": false,
  "confidence_score": 0.95
}

GET /api/v1/events/{job_id}/{event_id}/export​

  • Retrieve an event from Arcanna, in its raw format.
Example curl command:​
curl -X GET "https://api.arcanna.ai/api/v1/events/123/15427818711674/export" \
-H "x-arcanna-api-key: your-api-key-here"
Expected Response:​

Status Code: 200 OK

{
  "event_id": "15427818711674",
  "ingest_timestamp": "2024-02-15T11:50:13.781871Z",
  "status": "OK",
  "arcanna_event": {
    "example_field": "example_value"
  }
}

Event Feedback​

PUT /api/v1/events/{job_id}/{event_id}/feedback​

  • Provide feedback on a previously ingested event.
Example curl command:​
curl -X PUT "https://api.arcanna.ai/api/v1/events/123/15427818711674/feedback" \
-H "Content-Type: application/json" \
-H "x-arcanna-api-key: your-api-key-here" \
-d '{
  "cortex_user": "user123",
  "feedback": "positive"
}'
Expected Response:​

Status Code: 200 OK

{
  "status": "Feedback received"
}

Job Information​

GET /api/v1/jobs/​

  • Retrieve the list of jobs configured to ingest documents through the Arcanna REST API.
Example curl command:​
curl -X GET "https://api.arcanna.ai/api/v1/jobs/" \
-H "x-arcanna-api-key: your-api-key-here"
Expected Response:​

Status Code: 200 OK

[
  {
    "job_id": 123,
    "title": "Example Job",
    "status": "STARTED",
    "retrain_state": "not_trained",
    "labels": ["label1", "label2"],
    "processed_documents_count": 1000,
    "feedback_documents_count": 100,
    "last_processed_timestamp": "2024-02-15T11:50:13.781871Z"
  }
]

GET /api/v1/jobs/{job_id}​

  • Retrieve a specific job configured to ingest documents through the Arcanna REST API.
Example curl command:​
curl -X GET "https://api.arcanna.ai/api/v1/jobs/123" \
-H "x-arcanna-api-key: your-api-key-here"
Expected Response:​

Status Code: 200 OK

{
  "job_id": 123,
  "title": "Example Job",
  "status": "active",
  "retrain_state": "not_trained",
  "labels": ["label1", "label2"],
  "processed_documents_count": 1000,
  "feedback_documents_count": 100,
  "last_processed_timestamp": "2024-02-15T11:50:13.781871Z"
}

GET /api/v1/jobs/{job_id}/labels​

  • Retrieve the labels of a specific job configured to ingest documents through the Arcanna REST API.
Example curl command:​
curl -X GET "https://api.arcanna.ai/api/v1/jobs/123/labels" \
-H "x-arcanna-api-key: your-api-key-here"
Expected Response:​

Status Code: 200 OK

[
  "label1",
  "label2"
]

POST /api/v1/jobs/{job_id}/train​

  • Train a specific job.
Example curl command:​
curl -X POST "https://api.arcanna.ai/api/v1/jobs/123/train" \
-H "x-arcanna-api-key: your-api-key-here" \
-d '{
  "username": "johndoe"
}'
Expected Response:​

Status Code: 200 OK

{
  "status": "Training started"
}

POST /api/v1/jobs/get_by_name​

  • Retrieve a specific job configured to ingest documents through the Arcanna REST API.
Example curl command:​
curl -X POST "https://api.arcanna.ai/api/v1/jobs/get_by_name" \
-H "Content-Type: application/json" \
-H "x-arcanna-api-key: your-api-key-here" \
-d '{
  "job_name": "Example Job"
}'
Expected Response:​

Status Code: 200 OK

{
  "job_id": 123,
  "title": "Example Job",
  "status": "active",
  "retrain_state": "not_trained",
  "labels": ["label1", "label2"],
  "processed_documents_count": 1000,
  "feedback_documents_count": 100,
  "last_processed_timestamp": "2024-02-15T11:50:13.781871Z"
}

POST /api/v1/jobs/get_by_name/labels​

  • Retrieve the labels of a specific job configured to ingest documents through the Arcanna REST API.
Example curl command:​
curl -X POST "https://api.arcanna.ai/api/v1/jobs/get_by_name/labels" \
-H "Content-Type: application/json" \
-H "x-arcanna-api-key: your-api-key-here" \
-d '{
  "job_name": "Example Job"
}'
Expected Response:​

Status Code: 200 OK

[
  "label1",
  "label2"
]