Key Model Allowlist

GET

api

keys

{id}

models

Key Model Allowlist

curl --request GET \
  --url https://api.example.com/api/v1/keys/{id}/models \
  --header 'Content-Type: application/json' \
  --data '
{
  "model_ids": [
    "<string>"
  ]
}
'

import requests

url = "https://api.example.com/api/v1/keys/{id}/models"

payload = { "model_ids": ["<string>"] }
headers = {"Content-Type": "application/json"}

response = requests.get(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({model_ids: ['<string>']})
};

fetch('https://api.example.com/api/v1/keys/{id}/models', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/api/v1/keys/{id}/models",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_POSTFIELDS => json_encode([
    'model_ids' => [
        '<string>'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/api/v1/keys/{id}/models"

	payload := strings.NewReader("{\n  \"model_ids\": [\n    \"<string>\"\n  ]\n}")

	req, _ := http.NewRequest("GET", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.example.com/api/v1/keys/{id}/models")
  .header("Content-Type", "application/json")
  .body("{\n  \"model_ids\": [\n    \"<string>\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/api/v1/keys/{id}/models")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"model_ids\": [\n    \"<string>\"\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "key_id": "<string>",
  "inherits_all": true,
  "model_ids": [
    "<string>"
  ]
}

Each API key can carry an explicit model allowlist of Theo-branded model ids (e.g. theo-1-flash, theo-1-reason). An empty allowlist means the key inherits all models (the default). A non-empty allowlist restricts the key: any request that resolves to a model outside the list is rejected with 403 model_not_allowed — on both the native and OpenAI-compatible endpoints.

Authentication

Requires an API key with billing scope. The caller must own the key (or be a team member allowed to manage keys).

Path Parameters

string

required

The API key UUID.

Get the allowlist

GET /api/v1/keys/{id}/models

string

The API key UUID.

boolean

true when the allowlist is empty (the key can run any model).

string[]

The allowed Theo model ids (empty when inherits_all is true).

Replace the allowlist

PUT /api/v1/keys/{id}/models

string[]

required

The full set of Theo model ids to allow (e.g. ["theo-1-reason", "theo-1-code"]). Pass an empty array to reset the key to inherit all models. Unknown ids are rejected.

Example

curl -X PUT https://www.hitheo.ai/api/v1/keys/KEY_ID/models \
  -H "Authorization: Bearer $THEO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "model_ids": ["theo-1-reason", "theo-1-code"] }'

// Model binding is set via the dashboard or this REST endpoint.
// A request that resolves to a model outside the list throws TheoError(403, "model_not_allowed").

{ "key_id": "KEY_ID", "inherits_all": false, "model_ids": ["theo-1-reason", "theo-1-code"] }

Key Model Allowlist

curl --request GET \
  --url https://api.example.com/api/v1/keys/{id}/models \
  --header 'Content-Type: application/json' \
  --data '
{
  "model_ids": [
    "<string>"
  ]
}
'

import requests

url = "https://api.example.com/api/v1/keys/{id}/models"

payload = { "model_ids": ["<string>"] }
headers = {"Content-Type": "application/json"}

response = requests.get(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'GET',
  headers: {'Content-Type': 'application/json'},
  body: JSON.stringify({model_ids: ['<string>']})
};

fetch('https://api.example.com/api/v1/keys/{id}/models', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/api/v1/keys/{id}/models",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_POSTFIELDS => json_encode([
    'model_ids' => [
        '<string>'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/api/v1/keys/{id}/models"

	payload := strings.NewReader("{\n  \"model_ids\": [\n    \"<string>\"\n  ]\n}")

	req, _ := http.NewRequest("GET", url, payload)

	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.get("https://api.example.com/api/v1/keys/{id}/models")
  .header("Content-Type", "application/json")
  .body("{\n  \"model_ids\": [\n    \"<string>\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/api/v1/keys/{id}/models")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Content-Type"] = 'application/json'
request.body = "{\n  \"model_ids\": [\n    \"<string>\"\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "key_id": "<string>",
  "inherits_all": true,
  "model_ids": [
    "<string>"
  ]
}

Overview

Completions

Media Generation

Audio

Skills API

E.V.I. Canvas

Workflows

Hooks

Settings

Embed Widgets

Guardrails

Routing Studio

Theo Browser

Benchmarks

Webhooks

Billing

Resources

Authentication

Path Parameters

Get the allowlist

Replace the allowlist

Example

​Authentication

​Path Parameters

​Get the allowlist

​Replace the allowlist

​Example

Authentication

Path Parameters

Get the allowlist

Replace the allowlist

Example