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
013xrzp12g3nqk8nx0y2vfkg4s3jp2qr
external_identifier
string
id
One of:
AgentSchemaVersion_Id

A valid agent schema version ID

string
Example
013xrzp12g3nqk8nzntq40gkzaf2d9m2
span_result_schemas
One of:

Optional map of span type names to their result payload JSON schemas. Keys may be a subset of span_schemas; missing keys default to a schema requiring empty object. Only used when span_schemas is provided.

object
key
additional properties
object
key
additional properties
any
span_schemas
One of:

Map of span type names to their JSON schemas.

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
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
013xrzp12g3nqk8ngskn1wtxgka5b0nf
agent_id
Agent_Id

A valid agent ID

string
Example
013xrzp12g3nqk8nx0y2vfkg4s3jp2qr
current_version

Is this the agent’s current schema version?

boolean
environment_id
Environment_Id

A valid environment ID

string
Example
013xrzp12g3nqk8nzxvq7jm2arsfg5h1
external_identifier

External identifier for the agent schema version

string
Example
v0
id
AgentSchemaVersion_Id

A valid agent schema version ID

string
Example
013xrzp12g3nqk8nzntq40gkzaf2d9m2
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
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