Skip to content
Prefactor Docs

Create a new agent schema version

POST
/api/v1/agent_schema_version

Authorizations

Section titled “Authorizations ”

Request Body

Section titled “Request Body ”
AgentSchemaVersion_DetailsForCreate
object
agent_id
Agent_Id

A valid agent ID

string
Example
013xrzp12g3nqk8ns6jadrqmpgrjkeny
external_identifier
string
id
One of:
AgentSchemaVersion_Id

A valid agent schema version ID

string
Example
013xrzp12g3nqk8ns6jadrqmpgrjkeny
span_result_schemas
One of:
object
key
additional properties
object
key
additional properties
any
span_schemas
One of:
object
key
additional properties
object
key
additional properties
any
span_type_schemas
One of:

Array of span types with name, params_schema and optional result_schema.

Array<object>
SpanTypeSchemaDetails_ForCreate

One span type with name, params_schema and optional result_schema

object
data_risk
One of:
DataRisk
object
action_profile
required
ActionProfile
object
create_data
required

Creates data

string
Allowed values: unknown allowed disallowed
Example
unknown
destroy_data
required

Destroys data

string
Allowed values: unknown allowed disallowed
Example
unknown
external_communication
required

Sends external communications

string
Allowed values: unknown allowed disallowed
Example
unknown
financial_transactions
required

Performs financial transactions

string
Allowed values: unknown allowed disallowed
Example
unknown
read_data
required

Reads data

string
Allowed values: unknown allowed disallowed
Example
unknown
update_data
required

Updates data

string
Allowed values: unknown allowed disallowed
Example
unknown
params_data_categories
required
DataCategories
object
authentication_and_secrets
required

Authentication and secrets present

string
Allowed values: unknown included excluded
Example
unknown
behavioural_and_inferred
required

Behavioural and inferred data present

string
Allowed values: unknown included excluded
Example
unknown
classification
required

Classification level

string
Allowed values: unknown public internal confidential restricted secret
Example
unknown
contact_information
required

Contact information present

string
Allowed values: unknown included excluded
Example
unknown
criminal_justice
required

Criminal justice data present

string
Allowed values: unknown included excluded
Example
unknown
financial_information
required

Financial information present

string
Allowed values: unknown included excluded
Example
unknown
gdpr_biometric_for_identification
required

GDPR: biometric data for identification

string
Allowed values: unknown included excluded
Example
unknown
gdpr_genetic_data
required

GDPR: genetic data

string
Allowed values: unknown included excluded
Example
unknown
gdpr_political_opinions
required

GDPR: political opinions

string
Allowed values: unknown included excluded
Example
unknown
gdpr_racial_or_ethnic_origin
required

GDPR: racial or ethnic origin

string
Allowed values: unknown included excluded
Example
unknown
gdpr_religious_or_philosophical_beliefs
required

GDPR: religious or philosophical beliefs

string
Allowed values: unknown included excluded
Example
unknown
gdpr_sex_life_or_sexual_orientation
required

GDPR: sex life or sexual orientation

string
Allowed values: unknown included excluded
Example
unknown
gdpr_trade_union_membership
required

GDPR: trade union membership

string
Allowed values: unknown included excluded
Example
unknown
health_and_medical
required

Health and medical data present

string
Allowed values: unknown included excluded
Example
unknown
location_and_tracking
required

Location and tracking data present

string
Allowed values: unknown included excluded
Example
unknown
minors_data
required

Minors data present

string
Allowed values: unknown included excluded
Example
unknown
organisational_confidential
required

Organisational confidential data present

string
Allowed values: unknown included excluded
Example
unknown
personal_identifiers
required

Personal identifiers present

string
Allowed values: unknown included excluded
Example
unknown
result_data_categories
required
DataCategories
object
authentication_and_secrets
required

Authentication and secrets present

string
Allowed values: unknown included excluded
Example
unknown
behavioural_and_inferred
required

Behavioural and inferred data present

string
Allowed values: unknown included excluded
Example
unknown
classification
required

Classification level

string
Allowed values: unknown public internal confidential restricted secret
Example
unknown
contact_information
required

Contact information present

string
Allowed values: unknown included excluded
Example
unknown
criminal_justice
required

Criminal justice data present

string
Allowed values: unknown included excluded
Example
unknown
financial_information
required

Financial information present

string
Allowed values: unknown included excluded
Example
unknown
gdpr_biometric_for_identification
required

GDPR: biometric data for identification

string
Allowed values: unknown included excluded
Example
unknown
gdpr_genetic_data
required

GDPR: genetic data

string
Allowed values: unknown included excluded
Example
unknown
gdpr_political_opinions
required

GDPR: political opinions

string
Allowed values: unknown included excluded
Example
unknown
gdpr_racial_or_ethnic_origin
required

GDPR: racial or ethnic origin

string
Allowed values: unknown included excluded
Example
unknown
gdpr_religious_or_philosophical_beliefs
required

GDPR: religious or philosophical beliefs

string
Allowed values: unknown included excluded
Example
unknown
gdpr_sex_life_or_sexual_orientation
required

GDPR: sex life or sexual orientation

string
Allowed values: unknown included excluded
Example
unknown
gdpr_trade_union_membership
required

GDPR: trade union membership

string
Allowed values: unknown included excluded
Example
unknown
health_and_medical
required

Health and medical data present

string
Allowed values: unknown included excluded
Example
unknown
location_and_tracking
required

Location and tracking data present

string
Allowed values: unknown included excluded
Example
unknown
minors_data
required

Minors data present

string
Allowed values: unknown included excluded
Example
unknown
organisational_confidential
required

Organisational confidential data present

string
Allowed values: unknown included excluded
Example
unknown
personal_identifiers
required

Personal identifiers present

string
Allowed values: unknown included excluded
Example
unknown
description
One of:

Optional description

string
name
required

Span type name (e.g. llm, tool)

string
params_schema
required

JSON schema for the span payload

object
key
additional properties
any
result_schema
One of:

JSON schema for the span result payload. Defaults to empty object if omitted.

object
key
additional properties
any
template
One of:

Display template. Use {{field}} to interpolate params and result fields.

string
title
One of:

Human-readable title. Defaults to name when omitted.

string

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Success

object
details
AgentSchemaVersion_Details
object
account_id
Account_Id

A valid account ID

string
Example
013xrzp12g3nqk8ns6jadrqmpgrjkeny
agent_id
Agent_Id

A valid agent ID

string
Example
013xrzp12g3nqk8ns6jadrqmpgrjkeny
current_agent_deployment_refs

Agent deployments whose current version uses this schema version (empty if none).

Array<string>
external_identifier

External identifier for the agent schema version

string
Example
v0
external_identifier_repeats

Count of rows sharing this external identifier (helps distinguish duplicates).

integer
id
AgentSchemaVersion_Id

A valid agent schema version ID

string
Example
013xrzp12g3nqk8ns6jadrqmpgrjkeny
inserted_at

When the agent schema version was created

string format: date-time
Example
2024-01-01T00:00:00Z
span_type_schemas

Map of span type names to their params and result JSON schemas

object
key
additional properties
SpanTypeSchemaDetails
object
data_risk
DataRisk
object
action_profile
required
ActionProfile
object
create_data
required

Creates data

string
Allowed values: unknown allowed disallowed
Example
unknown
destroy_data
required

Destroys data

string
Allowed values: unknown allowed disallowed
Example
unknown
external_communication
required

Sends external communications

string
Allowed values: unknown allowed disallowed
Example
unknown
financial_transactions
required

Performs financial transactions

string
Allowed values: unknown allowed disallowed
Example
unknown
read_data
required

Reads data

string
Allowed values: unknown allowed disallowed
Example
unknown
update_data
required

Updates data

string
Allowed values: unknown allowed disallowed
Example
unknown
params_data_categories
required
DataCategories
object
authentication_and_secrets
required

Authentication and secrets present

string
Allowed values: unknown included excluded
Example
unknown
behavioural_and_inferred
required

Behavioural and inferred data present

string
Allowed values: unknown included excluded
Example
unknown
classification
required

Classification level

string
Allowed values: unknown public internal confidential restricted secret
Example
unknown
contact_information
required

Contact information present

string
Allowed values: unknown included excluded
Example
unknown
criminal_justice
required

Criminal justice data present

string
Allowed values: unknown included excluded
Example
unknown
financial_information
required

Financial information present

string
Allowed values: unknown included excluded
Example
unknown
gdpr_biometric_for_identification
required

GDPR: biometric data for identification

string
Allowed values: unknown included excluded
Example
unknown
gdpr_genetic_data
required

GDPR: genetic data

string
Allowed values: unknown included excluded
Example
unknown
gdpr_political_opinions
required

GDPR: political opinions

string
Allowed values: unknown included excluded
Example
unknown
gdpr_racial_or_ethnic_origin
required

GDPR: racial or ethnic origin

string
Allowed values: unknown included excluded
Example
unknown
gdpr_religious_or_philosophical_beliefs
required

GDPR: religious or philosophical beliefs

string
Allowed values: unknown included excluded
Example
unknown
gdpr_sex_life_or_sexual_orientation
required

GDPR: sex life or sexual orientation

string
Allowed values: unknown included excluded
Example
unknown
gdpr_trade_union_membership
required

GDPR: trade union membership

string
Allowed values: unknown included excluded
Example
unknown
health_and_medical
required

Health and medical data present

string
Allowed values: unknown included excluded
Example
unknown
location_and_tracking
required

Location and tracking data present

string
Allowed values: unknown included excluded
Example
unknown
minors_data
required

Minors data present

string
Allowed values: unknown included excluded
Example
unknown
organisational_confidential
required

Organisational confidential data present

string
Allowed values: unknown included excluded
Example
unknown
personal_identifiers
required

Personal identifiers present

string
Allowed values: unknown included excluded
Example
unknown
result_data_categories
required
DataCategories
object
authentication_and_secrets
required

Authentication and secrets present

string
Allowed values: unknown included excluded
Example
unknown
behavioural_and_inferred
required

Behavioural and inferred data present

string
Allowed values: unknown included excluded
Example
unknown
classification
required

Classification level

string
Allowed values: unknown public internal confidential restricted secret
Example
unknown
contact_information
required

Contact information present

string
Allowed values: unknown included excluded
Example
unknown
criminal_justice
required

Criminal justice data present

string
Allowed values: unknown included excluded
Example
unknown
financial_information
required

Financial information present

string
Allowed values: unknown included excluded
Example
unknown
gdpr_biometric_for_identification
required

GDPR: biometric data for identification

string
Allowed values: unknown included excluded
Example
unknown
gdpr_genetic_data
required

GDPR: genetic data

string
Allowed values: unknown included excluded
Example
unknown
gdpr_political_opinions
required

GDPR: political opinions

string
Allowed values: unknown included excluded
Example
unknown
gdpr_racial_or_ethnic_origin
required

GDPR: racial or ethnic origin

string
Allowed values: unknown included excluded
Example
unknown
gdpr_religious_or_philosophical_beliefs
required

GDPR: religious or philosophical beliefs

string
Allowed values: unknown included excluded
Example
unknown
gdpr_sex_life_or_sexual_orientation
required

GDPR: sex life or sexual orientation

string
Allowed values: unknown included excluded
Example
unknown
gdpr_trade_union_membership
required

GDPR: trade union membership

string
Allowed values: unknown included excluded
Example
unknown
health_and_medical
required

Health and medical data present

string
Allowed values: unknown included excluded
Example
unknown
location_and_tracking
required

Location and tracking data present

string
Allowed values: unknown included excluded
Example
unknown
minors_data
required

Minors data present

string
Allowed values: unknown included excluded
Example
unknown
organisational_confidential
required

Organisational confidential data present

string
Allowed values: unknown included excluded
Example
unknown
personal_identifiers
required

Personal identifiers present

string
Allowed values: unknown included excluded
Example
unknown
description
One of:

Optional description

string
name

Span type name

string
params_schema

JSON schema for the span payload

object
key
additional properties
any
params_schema_validation
SchemaValidationResult

Result of validating params_schema

object
message
One of:

Validation error message when status is ‘error’

string
status

Whether the schema is valid

string
Allowed values: success error
Example
success
result_schema

JSON schema for the span result payload (defaults to empty object if omitted when creating)

object
key
additional properties
any
result_schema_validation
SchemaValidationResult

Result of validating result_schema

object
message
One of:

Validation error message when status is ‘error’

string
status

Whether the schema is valid

string
Allowed values: success error
Example
success
template
One of:

Display template describing what happened in the span. Use {{field}} to interpolate params and result fields. Use imperative/command tense for params (e.g. “Generate {{content}}”) and past tense for result (e.g. “completed with {{finish_reason}}”).

string
title

Human-readable title (defaults to name)

string
Example
{
  "llm": {
    "name": "llm",
    "params_schema": {
      "properties": {
        "max_tokens": {
          "type": "integer"
        },
        "model": {
          "type": "string"
        },
        "temperature": {
          "type": "number"
        }
      },
      "type": "object"
    },
    "result_schema": {
      "properties": {
        "tokens": {
          "type": "integer"
        }
      },
      "type": "object"
    }
  },
  "tool": {
    "name": "tool",
    "params_schema": {
      "properties": {
        "input": {
          "type": "object"
        },
        "name": {
          "type": "string"
        }
      },
      "type": "object"
    },
    "result_schema": {
      "additionalProperties": false,
      "type": "object"
    }
  }
}
type

Type of resource (always ‘agent_schema_version’)

string
Allowed values: agent_schema_version
Example
agent_schema_version
updated_at

When the agent schema version was last updated

string format: date-time
Example
2024-01-01T00:00:00Z
status
string
Allowed values: success
Example
success

default

Section titled “default ”

Error

One of:
object
code
string
Allowed values: bad_request bad_authtoken not_authenticated not_permitted not_implemented unknown not_found unexpected_ref_type unexpected invalid_action invalid_value required_value idempotency_key_already_used
Example
bad_request
message
string
status
string
Allowed values: error
Example
error