Skip to main content

Input Operations

Overview​

The Input Operations API (/api/v1) provides endpoints for sending data to Arcanna, retrieving decisions, and providing feedback to improve AI models. This API can be used with all use cases configured with External REST API or Third-party input.

Authentication​

Authentication is done using the x-arcanna-api-key header with a token generated from:

  • Arcanna UI → Profile (top right) → API Keys
  • Or via the /api/v2/token endpoint in Swagger UI

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:

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

Status Code: 201 Created

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:

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

Status Code: 201 Created

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:

{
  "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
}

Status Code: 200 OK

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:

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

Status Code: 200 OK

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": "Feedback received"
}

Status Code: 200 OK

Use Case Information​

GET /api/v1/jobs/​

Retrieve the list of use cases 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:

[
  {
    "job_id": 123,
    "title": "Example Use Case",
    "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"
  }
]

Status Code: 200 OK

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

Retrieve a specific use case 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:

{
  "job_id": 123,
  "title": "Example Use Case",
  "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"
}

Status Code: 200 OK

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

Retrieve the labels of a specific use case 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:

[
  "label1",
  "label2"
]

Status Code: 200 OK

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": "Training started"
}

Status Code: 200 OK

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:

{
  "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"
}

Status Code: 200 OK

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:

[
  "label1",
  "label2"
]

Status Code: 200 OK