Create a new agent

POST

/api/v1/agent

const url = 'https://app.prefactorai.com/api/v1/agent';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"description":"Handles tier-1 support requests","external_identifier":"workflow-abc123","id":"013xrzp12g3nqk8ns6jadrqmpgrjkeny","name":"Support bot","owner_person_id":"013xrzp12g3nqk8ns6jadrqmpgrjkeny","risk_profile_id":"013xrzp12g3nqk8ns6jadrqmpgrjkeny","team_id":"013xrzp12g3nqk8ns6jadrqmpgrjkeny"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}

curl --request POST \
  --url https://app.prefactorai.com/api/v1/agent \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "description": "Handles tier-1 support requests", "external_identifier": "workflow-abc123", "id": "013xrzp12g3nqk8ns6jadrqmpgrjkeny", "name": "Support bot", "owner_person_id": "013xrzp12g3nqk8ns6jadrqmpgrjkeny", "risk_profile_id": "013xrzp12g3nqk8ns6jadrqmpgrjkeny", "team_id": "013xrzp12g3nqk8ns6jadrqmpgrjkeny" }'

Authorizations

authorization

Request Body

Agent_DetailsForCreate

object

description

Optional agent description

string

Example

Handles tier-1 support requests

external_identifier

Optional external identifier for this agent in an external system (unique per account)

string

Example

workflow-abc123

One of:

Agent_Id
Null

Agent_Id

A valid agent ID

string

Example

013xrzp12g3nqk8ns6jadrqmpgrjkeny

name

Agent name

string

Example

Support bot

owner_person_id

One of:

Person_Id
Null

Person_Id

A valid person ID

string

Example

013xrzp12g3nqk8ns6jadrqmpgrjkeny

risk_profile_id

One of:

RiskProfile_Id
Null

RiskProfile_Id

A valid risk profile ID

string

Example

013xrzp12g3nqk8ns6jadrqmpgrjkeny

team_id

One of:

Team_Id
Null

Team_Id

A valid team ID

string

Example

013xrzp12g3nqk8ns6jadrqmpgrjkeny

Responses

200

Success

application/json

object

details

Agent_Details

object

available_actions

Agent_AvailableActions

Available actions for this agent based on its status and instance counts

object

delete

Whether the agent can be deleted

boolean

reinstate

Whether the agent can be reinstated from retired

boolean

retire

Whether the agent can be retired

boolean

update

Whether the agent can be updated

boolean

description

One of:

string
Null

Agent description

string

external_identifier

One of:

string
Null

External identifier for this agent in an external system (unique per account)

string

Agent_Id

A valid agent ID

string

inserted_at

When the agent was created

string format: date-time

instance_counts

Agent_InstanceCounts

object

active

Number of instances with status active (running)

integer

cancelled

Number of instances with status cancelled

integer

complete

Number of instances with status complete

integer

failed

Number of instances with status failed

integer

finished

Number of instances in a finished state (complete + failed + cancelled + terminated)

integer

pending

Number of instances with status pending

integer

terminated

Number of instances with status terminated

integer

total

Total number of agent instances

integer

last_activity_span_at

One of:

string
Null

string format: date-time

name

Agent name

string

owner_person_id

One of:

Person_Id
Null

Person_Id

A valid person ID

string

risk_profile_id

One of:

RiskProfile_Id
Null

RiskProfile_Id

A valid risk profile ID

string

status

Agent status

string

Allowed values: pending active dormant retired

team_id

One of:

Team_Id
Null

Team_Id

A valid team ID

string

type

Type of resource (always ‘agent’)

string

Allowed values: agent

updated_at

When the agent was last updated

string format: date-time

status

string

Allowed values: success

Example

{
  "details": {
    "description": "Agent description",
    "external_identifier": "workflow-abc123",
    "id": "013xrzp12g3nqk8ns6jadrqmpgrjkeny",
    "inserted_at": "2024-01-01T00:00:00Z",
    "instance_counts": {
      "active": 2,
      "cancelled": 0,
      "complete": 5,
      "failed": 0,
      "finished": 5,
      "pending": 0,
      "terminated": 0,
      "total": 10
    },
    "last_activity_span_at": "2024-01-01T00:00:00Z",
    "name": "My Agent",
    "owner_person_id": "013xrzp12g3nqk8ns6jadrqmpgrjkeny",
    "risk_profile_id": "013xrzp12g3nqk8ns6jadrqmpgrjkeny",
    "status": "pending",
    "team_id": "013xrzp12g3nqk8ns6jadrqmpgrjkeny",
    "type": "agent",
    "updated_at": "2024-01-01T00:00:00Z"
  },
  "status": "success"
}

default

Error

application/json

One of:

object
object

object

code

string

Allowed values: bad_request bad_authtoken not_authenticated not_permitted not_implemented unknown not_found unexpected_ref_type unexpected invalid_action alert_unknown alert_already_cleared invalid_value required_value idempotency_key_already_used

message

string

status

string

Allowed values: error

Example

{
  "code": "bad_request",
  "status": "error"
}