DEVELOPER GUIDE

AI Model Trainer API

Connect the models you train to the tools you use.

Use your model directly in Google Sheets

StayCharted AI Model Trainer for Google Sheets is available from the Google Workspace Marketplace. Install the add-on for the spreadsheet workflow, or use the API recipes below for a custom integration.

Get it from Google Workspace Marketplace

Google Workspace Marketplace and the Google Workspace Marketplace logo are trademarks of Google LLC.

Classify from your own tools

Call the models you train in StayCharted AI Model Trainer from your own code, a spreadsheet, or an automation tool.

Base URL https://amt.staycharted.com

You train a model in the app by uploading examples you've already labelled. Then send it new text, or links to pictures, and get back a category and a confidence. Three endpoints cover everything:

Endpoint Use it for
GET /api/v1/models Listing the models you can call, and testing a key
POST /api/v1/models/{id}/classify One record in, one flat answer out. Best for Zapier, Make, Power Automate, Salesforce and spreadsheets
POST /api/v1/models/{id}/predict One record, or up to 100 at once. Best for your own code

The API is included on Essentials and Business. See Pricing.

Or call it from your own code, with one record in and one answer out.

POST https://amt.staycharted.com/api/v1/models/{id}/classify
Authorization: Bearer amt_live_…

{ "input": "I was charged twice this month" }

→ { "label": "Billing",
    "confidence": 0.94,
    "needsReview": false,
    "modelName": "Support ticket routing" }
API guide →

Classify a batch

POST https://amt.staycharted.com/api/v1/models/{id}/predict
Authorization: Bearer amt_live_…

{ "inputs": ["I was charged twice", "Where is my parcel?"] }

→ { "predictions": [
      { "label": "Billing", "confidence": 0.94, "needsReview": false },
      { "label": "Delivery", "confidence": 0.71, "needsReview": true } ],
    "usage": { "predictions": 2 } }
API guide →

Get started in three steps

1. Create a key. Sign in to AI Model Trainer, open Workspaces → your workspace → API keys, and create one.

  • The full key (it starts with amt_live_) is shown once. Store it then.
  • Up to ten keys can be active at once. Give each integration its own, so you can revoke one without breaking the others.

2. Find your model's id. It's listed on the same screen. Or call GET /api/v1/models, which also confirms the key works and costs nothing. Only published models can be called.

3. Classify something.

Show Command example
curl -sS https://amt.staycharted.com/api/v1/models/$MODEL_ID/classify \
  -H "Authorization: Bearer $STAYCHARTED_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"input":"My invoice charged me twice this month"}'
Show JSON example
{
  "label": "Billing",
  "confidence": 0.94,
  "modelId": "8f14e45f-ceea-467a-9b2c-1d5c2b0e7a11",
  "modelName": "Support tickets"
}

label is the answer. confidence runs from 0 to 1.

What it costs, and the one limit to design around

Every record is one prediction, drawn from the same monthly allowance your file fills in the app use. A request that is refused, for any reason below, costs nothing.

The rate limit is counted in records per minute, for the whole workspace: 30 a minute on Essentials, 60 on Business.

  • Every key draws on that one allowance, so adding keys doesn't add throughput.
  • The allowance refills continuously; it doesn't reset on the minute.
  • A request that doesn't fit is refused whole with 429 and a Retry-After header, and nothing is charged.

So the API is for a steady trickle, not a flood. It suits a ticket as it arrives, a row as it's created, a form as it's submitted. For thousands of rows, upload the file in the app instead, or fill straight from a Snowflake or Databricks table. It runs in one pass on hardware sized for the job, and you download the filled file.

Recipes

Suggest access for a new SharePoint file (Power Automate)

Send the new file’s location to a model trained on your permission export. Use its suggested groups, permission levels and review status in your approval workflow. Follow SharePoint access with Power Automate.

Fill rows in Snowflake or Databricks

No API call needed: connect the warehouse in Settings → Warehouses, fill from a table, and read the answers from the results table in your own SQL. A scheduled job can join them back. Follow Train and fill from Snowflake and Databricks.

Google Sheets: custom Apps Script recipe

For the ready-made add-on, get StayCharted AI Model Trainer from the Google Workspace Marketplace. The =CLASSIFY(A2) example below is a separate custom Apps Script integration; it is not a built-in function supplied by the add-on.

In your sheet: Extensions → Apps Script, paste this, save, and go back to the sheet.

Show JavaScript example
const STAYCHARTED_KEY   = 'amt_live_...';  // your API key
const STAYCHARTED_MODEL = '8f14e45f-...';  // your model id

/**
 * Classify one cell.
 * @param {string} text The cell to classify.
 * @return {string} The label.
 * @customfunction
 */
function CLASSIFY(text) {
  if (!text || !String(text).trim()) return '';

  const url = 'https://amt.staycharted.com/api/v1/models/'
    + STAYCHARTED_MODEL + '/classify';

  // Two attempts: a column of formulas recalculates all at once and the
  // per-minute allowance is shared. Retry-After says exactly how long to wait.
  for (let attempt = 0; attempt < 2; attempt++) {
    const res = UrlFetchApp.fetch(url, {
      method: 'post',
      contentType: 'application/json',
      headers: { Authorization: 'Bearer ' + STAYCHARTED_KEY },
      payload: JSON.stringify({ input: String(text) }),
      muteHttpExceptions: true,
    });

    const code = res.getResponseCode();
    if (code === 200) return JSON.parse(res.getContentText()).label || '';

    if (code === 429 && attempt === 0) {
      const wait = Number(res.getAllHeaders()['Retry-After'] || 5);
      Utilities.sleep(Math.min(wait, 25) * 1000);
      continue;
    }
    // Show the reason rather than an empty cell.
    return 'ERR ' + code + ': ' + (JSON.parse(res.getContentText()).code || '');
  }
  return 'ERR rate limited';
}

Then type =CLASSIFY(A2) in a cell and drag it down.

  • Start with a few rows at a time. Sheets recalculates the whole column at once. Large selections can exceed the shared rate limit and return ERR rate limited. For more than a few hundred rows, fill the file in the app instead.
  • The key travels with the sheet. Anyone you share the sheet with can read the script. Give it its own key, and revoke the key when you're done.

Zapier

Add a Webhooks by Zapier → Custom Request action.

Field Value
Method POST
URL https://amt.staycharted.com/api/v1/models/<MODEL_ID>/classify
Data Pass-Through? no
Data {"input": "<the field from your trigger>"}
Headers Authorization: Bearer <YOUR_API_KEY> and Content-Type: application/json

The next step can use label, confidence, modelId and modelName as plain fields. Zapier counts one task per action, so a thousand records is a thousand tasks.

Make

Add HTTP → Make a request.

  • URL: https://amt.staycharted.com/api/v1/models/<MODEL_ID>/classify
  • Method: POST
  • Headers: Authorization = Bearer <YOUR_API_KEY>
  • Body type: Raw, content type application/json
  • Request content: {"input": "{{yourField}}"}
  • Parse response: yes. Without it, the next module sees a string instead of label.

Your own code: /predict for batches

Send up to 100 records in one call. Answers come back in the order sent, each with its input echoed.

Show Command example
curl -sS https://amt.staycharted.com/api/v1/models/$MODEL_ID/predict \
  -H "Authorization: Bearer $STAYCHARTED_KEY" \
  -H 'Content-Type: application/json' \
  -d '{"inputs":["My invoice charged me twice this month","The parcel arrived with a cracked screen"]}'
Show JSON example
{
  "model": { "id": "8f14e45f-ceea-467a-9b2c-1d5c2b0e7a11", "name": "Support tickets" },
  "predictions": [
    { "input": "My invoice charged me twice this month", "label": "Billing", "confidence": 0.94 },
    { "input": "The parcel arrived with a cracked screen", "label": "Shipping", "confidence": 0.71 }
  ],
  "usage": { "predictions": 2 }
}

The whole request is checked against your remaining monthly allowance before any of it runs. A request that would go over is refused entirely, never half-answered.

AI assistants

To use your models from Claude or ChatGPT instead of code, connect the assistant instead. See Use AI Model Trainer from Claude and ChatGPT.

Reference

Authentication

Send your key in every request:

Show HTTP example
Authorization: Bearer amt_live_…

Keys are created and revoked only in the app, never through the API. A key that could create keys couldn't really be revoked.

GET /api/v1/models

Lists the models this key can call. A model appears only when it is published, switched on, and allowed by your plan. This call spends no predictions and has its own allowance of 60 requests a minute.

Show JSON example
{
  "workspace": { "id": "2fd16021-706c-4608-b488-9d0c267c7f28", "name": "Support", "owner": "Sam Patel" },
  "models": [
    {
      "id": "8f14e45f-ceea-467a-9b2c-1d5c2b0e7a11",
      "name": "Support tickets",
      "custom": true,
      "modality": "text",
      "inputs": ["Subject", "Body"],
      "answer": { "shape": "record", "fields": ["Category", "Assignment group"] }
    },
    {
      "id": "3c59dc04-8e88-4950-9f2b-7a1c2a1e0b02",
      "name": "Product feedback",
      "custom": false,
      "modality": "text",
      "inputs": ["Feedback"],
      "answer": { "shape": "single", "fields": ["Area"] }
    }
  ]
}
Response field Type Notes
workspace.id string The workspace this key belongs to.
workspace.name string or null Its name, as the app's workspace switcher shows it.
workspace.owner string or null Who shared it: their name, or their email address when they haven't given one.
id string The model's id. Use it in every other call.
name string
custom boolean true for a Dedicated AI Model; false for a Classifier Model or an AI Classifier Model. All of them are called the same way.
modality string text or image: what the model reads.
inputs array The columns the model was trained on. Send these as the keys of input.
answer.shape string single (one category), list (a set of categories, returned in labels) or record (several answer columns, returned in fields).
answer.fields array The names of the answer's parts.

Integrations use workspace to label a saved connection, so two keys can be told apart.

GET /api/v1/models/{id}

One model, with the forms to call it. It returns the same fields as the list, plus two JSON Schemas built from them: inputSchema, the fields to send as input to classify, and answerSchema, what classify returns for this model. Tools that build forms from a schema (Zapier, Power Automate) use these; anything else can use inputs and answer.

It shares the model list's allowance, 60 requests a minute, and spends no predictions. A model that isn't published, or that your plan can't call, returns 404 api.model_not_found.

Show JSON example
{
  "id": "8f14e45f-ceea-467a-9b2c-1d5c2b0e7a11",
  "name": "Support tickets",
  "custom": true,
  "modality": "text",
  "inputs": ["Subject", "Body"],
  "answer": { "shape": "record", "fields": ["Category", "Assignment group"] },
  "inputSchema": {
    "type": "object",
    "properties": {
      "Subject": { "type": "string", "title": "Subject" },
      "Body": { "type": "string", "title": "Body" }
    }
  },
  "answerSchema": {
    "type": "object",
    "properties": {
      "label": { "type": "string", "title": "Answer" },
      "confidence": { "type": "number", "title": "Confidence (0 to 1)" },
      "needsReview": { "type": "boolean", "title": "Needs review" },
      "fields": {
        "type": "object",
        "title": "Answer fields",
        "properties": {
          "Category": { "type": "string", "title": "Category" },
          "Assignment group": { "type": "string", "title": "Assignment group" }
        }
      }
    }
  }
}

The schemas may carry extra keys some tools read (for example x-ms-visibility); other clients can ignore them.

POST /api/v1/models/{id}/classify

One record in, one flat answer out.

Request field Type Notes
input string, or object Text model: text or a record with the training column names. Picture model: a link to the picture (http or https), or {"imageBase64": "..."} for a picture under 1.5 MB.
Response field Type Notes
label string or null The category.
labels array A list answer, when the model learns a set of categories.
fields object Answers for the model’s separate answer columns.
needsReview boolean True when the answer is below the model’s review cutoff.
confidence number or null 0 to 1.
modelId string
modelName string
error string Picture models only, when the picture couldn't be used. See below.
message string The same reason in plain words.

POST /api/v1/models/{id}/predict

Exactly one of:

Request field Type Notes
input string One record.
inputs array 1 to 100 records. For a picture model: up to 20 pictures, each a link or {"imageBase64": "..."}.
Response field Type Notes
model.id, model.name string
predictions[] array One per input, in order: input, label, labels, fields, confidence, needsReview, and for a picture that couldn't be used, error and message.
usage.predictions integer Records counted against this month's allowance.

predictions is always an array, even for a single input.

Records, permission exports and pictures with text

For a text model trained on several columns, send a record with the same column names:

Show JSON example
{"input": {"Subject": "Refund request", "Body": "I was charged twice"}}

For a model trained on a SharePoint permission export, send the location as Path, URL, webUrl or Resource Path, with or without the full URL:

Show JSON example
{"input": {"Path": "/sites/Finance/Shared Documents/Invoices/new.pdf"}}

For a picture model trained with a text column, send both the photo and its note, or text alone when there is no photo:

Show JSON example
{"input": {"image": "https://example.com/parcel.jpg", "text": "Corner crushed on arrival"}}
Show JSON example
{"input": {"text": "Corner crushed on arrival"}}

Successful answers include needsReview alongside the category and confidence, with labels or fields when applicable to the model’s answer format. Picture errors may omit these fields.

Pictures

For a model that reads pictures:

  • Each picture counts once against your monthly picture allowance, as well as once as a prediction.
  • A picture that can't be used comes back with label and confidence set to null, plus an error code and a message, and isn't counted. The codes are: not_found, forbidden, unreachable, timeout, too_large, web_page, not_an_image, unsupported_format, too_small, corrupt, blocked_address, not_a_link.
  • Accepted formats: JPEG, PNG, WebP, GIF, BMP and TIFF.

Rate-limit headers

Header Meaning
X-RateLimit-Limit Records a minute your plan allows, for the whole workspace.
X-RateLimit-Remaining Records you can send right now.
Retry-After On a 429: seconds until this request will fit. A smaller request may fit sooner.

Errors

Every error is JSON with a stable code. Branch on code, never on the error sentence, which is written for people and may be reworded.

A refusal caused by your plan also carries entitlement, limit, used, resetsAt and upgrade. Those let a client tell "wait until the month resets" from "this plan will never allow it".

HTTP code What it means, and what to do
400 api.input_missing classify got no usable input. It takes one text or record input; an array is /predict's shape.
400 api.input_required /predict needs input (one record) or inputs (an array).
400 api.input_invalid Each input must contain usable text or an accepted record.
400 api.too_many_inputs More than 100 records in one request. Send several requests, or fill the file in the app.
400 api.too_many_images More than 20 pictures in one request.
400 api.text_input_invalid This model reads text: send text or a record with the training column names.
400 api.image_input_invalid This model reads pictures: send a link or {"imageBase64": "..."}.
400 api.image_too_large A picture sent in the request is over 1.5 MB. Send a link instead.
401 api.key_missing No Authorization: Bearer <key> header.
401 api.key_invalid The key is wrong or revoked. Create a new one.
402 plan.feature_not_included The API isn't on this plan. Retrying won't help; upgrade names the plan that includes it.
402 plan.prediction_limit This month's predictions are used up. resetsAt says when they come back.
403 account.suspended Contact support.
404 api.model_not_found Wrong model id, or the model is in another workspace.
409 api.model_not_deployed The model is trained but not published. Publish it in the app.
409 api.model_needs_retraining The model must be retrained before it can answer again. Its owner retrains it in the app.
429 api.rate_limited Over the per-minute allowance. Wait Retry-After seconds.
503 api.model_unavailable A service the model needs is briefly unavailable, usually during a restart. Retry after a short wait. Nothing was charged.

Connect apps with Zapier

Classify emails, leads and tickets with your StayCharted model in Zapier →

Connect apps with Make

Classify emails, leads and tickets with Make’s HTTP module →

Connect Microsoft workflows

Classify files and list items with Power Automate →

SharePoint access with Power Automate →

Partner API

For software companies building StayCharted into their product: Partner API reference · OpenAPI 3.0 · Become a solution partner.

Need help connecting?

Contact support@staycharted.com.

Get an API key →