Ask typed questions

The SystemOne-compatible API: typed questions about any state.

POST /api/v1/systemone. The fields, answers and errors below are rendered from the OpenAPI document.

Ask typed questions

POST /api/v1/systemone

The SystemOne-compatible API, which works like any decision model: typed questions (choice, score, noul) about any state, answered in one pass with probabilities.

Request body

application/json

object

model (optional)
string
Allowed values
["eevo-1"]
Default
"eevo-1"
state (required)
Variants:
- string
  Minimum length
  1
  Maximum length
  50000
- object
  Additional property values:
questions (required)
object
Additional property values:
Variants:
- object
  - type (required)
    string
    Allowed values
    ["choice"]
  - instructions (optional)
    string
    Maximum length
    2000
  - criteria (required)
    object
    Additional property values:
    string
    Maximum length
    2000
  Additional properties: not allowed.
- object
  - type (required)
    string
    Allowed values
    ["score"]
  - instructions (optional)
    string
    Maximum length
    2000
  - criteria (required)
    array
    Minimum items
    2
    Maximum items
    64
    Array items:
    string
    Maximum length
    500
  Additional properties: not allowed.
- object
  - type (required)
    string
    Allowed values
    ["noul"]
  - instructions (optional)
    string
    Maximum length
    2000
  Additional properties: not allowed.
metadata (optional)
object
- conversation (optional)
  object
  - platform (required)
    string
    Allowed values
    ["slack","teams","google_chat","other"]
  - channel (optional)
    string
    Minimum length
    1
    Maximum length
    200
  - thread_url (optional)
    string
    Minimum length
    1
    Maximum length
    2000
  Additional properties: not allowed.
- issue (optional)
  object
  - tracker (required)
    string
    Allowed values
    ["linear","jira","github","other"]
  - url (required)
    string
    Minimum length
    1
    Maximum length
    2000
  - key (optional)
    string
    Minimum length
    1
    Maximum length
    100
  - title (optional)
    string
    Minimum length
    1
    Maximum length
    300
  Additional properties: not allowed.
- pull_request (optional)
  object
  - platform (required)
    string
    Allowed values
    ["github","gitlab","bitbucket","azure_devops","other"]
  - url (required)
    string
    Minimum length
    1
    Maximum length
    2000
  - repo (optional)
    string
    Minimum length
    1
    Maximum length
    200
  - number (optional)
    integer
    Minimum
    0
    Exclusive minimum
    true
  - title (optional)
    string
    Minimum length
    1
    Maximum length
    300
  Additional properties: not allowed.
- on_behalf_of (optional)
  object
  - name (optional)
    string
    Minimum length
    1
    Maximum length
    200
  - email (optional)
    string · email
    Maximum length
    320
  Additional properties: not allowed.
- links (optional)
  array
  Maximum items
  10
  Array items:
  object
  - url (required)
    string
    Minimum length
    1
    Maximum length
    2000
  - label (optional)
    string
    Minimum length
    1
    Maximum length
    200
  Additional properties: not allowed.
Additional properties: not allowed.
share_with_org (optional)
boolean

Additional properties: not allowed.

Example:

{
  "model": "eevo-1",
  "state": "Support ticket: a customer was charged twice for an €80 order because of an error in our billing system. Agents may refund up to €50 without approval.",
  "questions": {
    "action": {
      "type": "choice",
      "instructions": "What should the support agent do?",
      "criteria": {
        "refuse": "Refuse, and cite the €50 limit",
        "partial": "Refund €50 and ask the customer to contact billing for the rest",
        "refund": "Refund the €80 duplicate charge and record the exception"
      }
    },
    "urgency": {
      "type": "score",
      "instructions": "How urgent is the ticket?",
      "criteria": [
        "Not urgent",
        "Somewhat urgent",
        "Urgent",
        "Critical"
      ]
    },
    "fraud": {
      "type": "noul",
      "instructions": "The customer is attempting fraud."
    }
  }
}

Responses

Response 200

One answer per question.

application/json

object

id (optional)
string
Request id, as in the Eevo console decision log.
model (required)
string
answers (required)
object
Additional property values:
object
- type (required)
  string
  Allowed values
  ["choice","score","noul"]
Additional properties: allowed.
usage (required)
object
- input_tokens (required)
  number
- output_tokens (required)
  number
Additional properties: not allowed.

Additional properties: not allowed.

Example:

{
  "model": "eevo-1",
  "answers": {
    "action": {
      "type": "choice",
      "choice": "refund",
      "confidence": 0.71,
      "probabilities": {
        "refuse": 0.07,
        "partial": 0.22,
        "refund": 0.71
      }
    },
    "urgency": {
      "type": "score",
      "score": 2,
      "confidence": 0.58,
      "legend": {
        "0": "Not urgent",
        "1": "Somewhat urgent",
        "2": "Urgent",
        "3": "Critical"
      },
      "probabilities": {
        "0": 0.03,
        "1": 0.31,
        "2": 0.58,
        "3": 0.08
      }
    },
    "fraud": {
      "type": "noul",
      "noul": 0.04
    }
  },
  "usage": {
    "input_tokens": 412,
    "output_tokens": 0
  }
}

Response 400

The request is invalid; the message says which field and why.

application/json

Error

object

error (required)
object
- type (required)
  string
  Allowed values
  ["invalid_request","authentication","insufficient_credit","model_unavailable","model_warming","free_capacity_busy","too_many_overlap_pairs","too_many_records","revision_conflict","rate_limited","server_error"]
- message (required)
  string

Response 401

No valid API key.

application/json

Error

object

error (required)
object
- type (required)
  string
  Allowed values
  ["invalid_request","authentication","insufficient_credit","model_unavailable","model_warming","free_capacity_busy","too_many_overlap_pairs","too_many_records","revision_conflict","rate_limited","server_error"]
- message (required)
  string

Response 402

No free decisions or credit left for the request.

application/json

Error

object

error (required)
object
- type (required)
  string
  Allowed values
  ["invalid_request","authentication","insufficient_credit","model_unavailable","model_warming","free_capacity_busy","too_many_overlap_pairs","too_many_records","revision_conflict","rate_limited","server_error"]
- message (required)
  string

Response 403

Only the person who made the decision, or the API key it was made with, can change who sees it or publish it.

application/json

Error

object

error (required)
object
- type (required)
  string
  Allowed values
  ["invalid_request","authentication","insufficient_credit","model_unavailable","model_warming","free_capacity_busy","too_many_overlap_pairs","too_many_records","revision_conflict","rate_limited","server_error"]
- message (required)
  string

Response 409

The model is not served yet, or the revised decision already has a newer revision.

application/json

Error

object

error (required)
object
- type (required)
  string
  Allowed values
  ["invalid_request","authentication","insufficient_credit","model_unavailable","model_warming","free_capacity_busy","too_many_overlap_pairs","too_many_records","revision_conflict","rate_limited","server_error"]
- message (required)
  string

Response 410

No such decision that you can see: none in your organization, or one not shared with you.

application/json

Error

object

error (required)
object
- type (required)
  string
  Allowed values
  ["invalid_request","authentication","insufficient_credit","model_unavailable","model_warming","free_capacity_busy","too_many_overlap_pairs","too_many_records","revision_conflict","rate_limited","server_error"]
- message (required)
  string

Response 429

Rate limit reached (see Retry-After), or your organization already has 3 Default mode decisions running; send it when one is done.

application/json

Error

object

error (required)
object
- type (required)
  string
  Allowed values
  ["invalid_request","authentication","insufficient_credit","model_unavailable","model_warming","free_capacity_busy","too_many_overlap_pairs","too_many_records","revision_conflict","rate_limited","server_error"]
- message (required)
  string

Response 502

The model failed to answer, or the decision could not be completed. Nothing is billed.

application/json

Error

object

error (required)
object
- type (required)
  string
  Allowed values
  ["invalid_request","authentication","insufficient_credit","model_unavailable","model_warming","free_capacity_busy","too_many_overlap_pairs","too_many_records","revision_conflict","rate_limited","server_error"]
- message (required)
  string

Response 503

The model is starting after being idle, or a request on free decisions found it busy (free_capacity_busy); retry after Retry-After seconds. Nothing is billed.

application/json

Error

object

error (required)
object
- type (required)
  string
  Allowed values
  ["invalid_request","authentication","insufficient_credit","model_unavailable","model_warming","free_capacity_busy","too_many_overlap_pairs","too_many_records","revision_conflict","rate_limited","server_error"]
- message (required)
  string

Ask typed questions: examples

Request example

curl -X POST 'https://eevo.io/api/v1/systemone' \
  -H "Authorization: Bearer $EEVO_API_KEY" \
  -H 'Content-Type: application/json' \
  -d '{
  "model": "eevo-1",
  "state": "Support ticket: a customer was charged twice for an €80 order because of an error in our billing system. Agents may refund up to €50 without approval.",
  "questions": {
    "action": {
      "type": "choice",
      "instructions": "What should the support agent do?",
      "criteria": {
        "refuse": "Refuse, and cite the €50 limit",
        "partial": "Refund €50 and ask the customer to contact billing for the rest",
        "refund": "Refund the €80 duplicate charge and record the exception"
      }
    },
    "urgency": {
      "type": "score",
      "instructions": "How urgent is the ticket?",
      "criteria": [
        "Not urgent",
        "Somewhat urgent",
        "Urgent",
        "Critical"
      ]
    },
    "fraud": {
      "type": "noul",
      "instructions": "The customer is attempting fraud."
    }
  }
}'

Response 200 example

{
  "model": "eevo-1",
  "answers": {
    "action": {
      "type": "choice",
      "choice": "refund",
      "confidence": 0.71,
      "probabilities": {
        "refuse": 0.07,
        "partial": 0.22,
        "refund": 0.71
      }
    },
    "urgency": {
      "type": "score",
      "score": 2,
      "confidence": 0.58,
      "legend": {
        "0": "Not urgent",
        "1": "Somewhat urgent",
        "2": "Urgent",
        "3": "Critical"
      },
      "probabilities": {
        "0": 0.03,
        "1": 0.31,
        "2": 0.58,
        "3": 0.08
      }
    },
    "fraud": {
      "type": "noul",
      "noul": 0.04
    }
  },
  "usage": {
    "input_tokens": 412,
    "output_tokens": 0
  }
}