Design an Agent

Design an agent from a description

curl --request POST \
  --url https://api.instaview.sk/agents/composer \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data @- <<EOF
{
  "message": "Screen senior backend devs. Ask about Go and Postgres, check notice period and salary expectation, then hand off to a recruiter if they're a strong fit.",
  "type": "PHONE",
  "name": "Senior Developer Phone Screen",
  "duration": 90.5,
  "voiceId": "<string>",
  "companyPhoneNumberId": "<string>",
  "metadata": {}
}
EOF

import requests

url = "https://api.instaview.sk/agents/composer"

payload = {
    "message": "Screen senior backend devs. Ask about Go and Postgres, check notice period and salary expectation, then hand off to a recruiter if they're a strong fit.",
    "type": "PHONE",
    "name": "Senior Developer Phone Screen",
    "duration": 90.5,
    "voiceId": "<string>",
    "companyPhoneNumberId": "<string>",
    "metadata": {}
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    message: 'Screen senior backend devs. Ask about Go and Postgres, check notice period and salary expectation, then hand off to a recruiter if they\'re a strong fit.',
    type: 'PHONE',
    name: 'Senior Developer Phone Screen',
    duration: 90.5,
    voiceId: '<string>',
    companyPhoneNumberId: '<string>',
    metadata: {}
  })
};

fetch('https://api.instaview.sk/agents/composer', 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.instaview.sk/agents/composer",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'message' => 'Screen senior backend devs. Ask about Go and Postgres, check notice period and salary expectation, then hand off to a recruiter if they\'re a strong fit.',
    'type' => 'PHONE',
    'name' => 'Senior Developer Phone Screen',
    'duration' => 90.5,
    'voiceId' => '<string>',
    'companyPhoneNumberId' => '<string>',
    'metadata' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "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.instaview.sk/agents/composer"

	payload := strings.NewReader("{\n  \"message\": \"Screen senior backend devs. Ask about Go and Postgres, check notice period and salary expectation, then hand off to a recruiter if they're a strong fit.\",\n  \"type\": \"PHONE\",\n  \"name\": \"Senior Developer Phone Screen\",\n  \"duration\": 90.5,\n  \"voiceId\": \"<string>\",\n  \"companyPhoneNumberId\": \"<string>\",\n  \"metadata\": {}\n}")

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

	req.Header.Add("Authorization", "Bearer <token>")
	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.post("https://api.instaview.sk/agents/composer")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"message\": \"Screen senior backend devs. Ask about Go and Postgres, check notice period and salary expectation, then hand off to a recruiter if they're a strong fit.\",\n  \"type\": \"PHONE\",\n  \"name\": \"Senior Developer Phone Screen\",\n  \"duration\": 90.5,\n  \"voiceId\": \"<string>\",\n  \"companyPhoneNumberId\": \"<string>\",\n  \"metadata\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.instaview.sk/agents/composer")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"message\": \"Screen senior backend devs. Ask about Go and Postgres, check notice period and salary expectation, then hand off to a recruiter if they're a strong fit.\",\n  \"type\": \"PHONE\",\n  \"name\": \"Senior Developer Phone Screen\",\n  \"duration\": 90.5,\n  \"voiceId\": \"<string>\",\n  \"companyPhoneNumberId\": \"<string>\",\n  \"metadata\": {}\n}"

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

{
  "sessionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "agent": {
    "type": "ONLINE",
    "flow": {
      "firstMessage": {
        "type": "first_message",
        "text": "Hi {{contact.firstName}}, do you have two minutes?",
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "label": "Qualify budget"
      },
      "sections": [
        {
          "type": "sequential",
          "prompt": "Introduce yourself and explain why you are calling.",
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "label": "Qualify budget"
        }
      ],
      "lastMessage": {
        "type": "last_message",
        "text": "Thanks for your time — have a great day!",
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "label": "Qualify budget"
      },
      "schemaVersion": "1.0.0"
    },
    "name": "Senior Developer Phone Screen",
    "language": "EN",
    "duration": 123,
    "voiceId": "<string>",
    "backgroundSound": "OFFICE",
    "companyPhoneNumberId": "<string>",
    "metadata": {},
    "overrides": {
      "companyName": "Acme Manufacturing",
      "companyDescription": "Acme makes industrial fasteners and employs 400 people across Slovakia."
    },
    "guardrails": {
      "rules": [
        "Never quote a price",
        "Never promise a delivery date"
      ]
    },
    "contextConfig": {
      "role": "an account executive for Acme",
      "communicationStyle": "concise and direct",
      "callToAction": "book a 30-minute demo"
    },
    "analyticsConfig": {
      "extractionTargets": [
        {
          "label": "Budget confirmed",
          "type": "bool",
          "key": "budget_confirmed",
          "enumValues": [
            "hot",
            "warm",
            "cold"
          ],
          "ideal": "A confirmed budget of at least 10k",
          "importance": "PREFERRED",
          "weight": 40
        }
      ],
      "scoringCriteria": [
        {
          "label": "Handled objections",
          "description": "Acknowledged the objection and answered it with a concrete example",
          "key": "handled_objections",
          "importance": "PREFERRED",
          "weight": 40
        }
      ],
      "outcomes": [
        {
          "label": "Meeting booked",
          "description": "The contact agreed to a specific date and time",
          "key": "meeting_booked"
        }
      ],
      "outputTags": [
        {
          "label": "Needs follow-up",
          "key": "needs_followup",
          "description": "The contact asked to be called back"
        }
      ],
      "capture": {
        "recording": true,
        "transcript": true,
        "summary": true,
        "qa": true,
        "evaluation": true,
        "sentiment": true
      }
    }
  },
  "message": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "role": "user",
    "content": "Your agent opens by introducing itself and confirming it's speaking with the right person. It then works through Go and Postgres experience…",
    "createdAt": "2023-11-07T05:31:56Z",
    "changes": [
      "Added a relocation question",
      "Set the language to Slovak"
    ]
  },
  "expiresAt": "2023-11-07T05:31:56Z"
}

{
  "statusCode": 422,
  "message": "Invalid conversation flow.",
  "errors": [
    {
      "code": "UNKNOWN_BLOCK_TYPE",
      "message": "Unknown block type: teleport.",
      "path": "sections[2].branches[0].blocks[1]"
    }
  ],
  "traceId": "6a707aee000000000c1e285eefed9980"
}

POST

agents

composer

Design an agent from a description

curl --request POST \
  --url https://api.instaview.sk/agents/composer \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data @- <<EOF
{
  "message": "Screen senior backend devs. Ask about Go and Postgres, check notice period and salary expectation, then hand off to a recruiter if they're a strong fit.",
  "type": "PHONE",
  "name": "Senior Developer Phone Screen",
  "duration": 90.5,
  "voiceId": "<string>",
  "companyPhoneNumberId": "<string>",
  "metadata": {}
}
EOF

import requests

url = "https://api.instaview.sk/agents/composer"

payload = {
    "message": "Screen senior backend devs. Ask about Go and Postgres, check notice period and salary expectation, then hand off to a recruiter if they're a strong fit.",
    "type": "PHONE",
    "name": "Senior Developer Phone Screen",
    "duration": 90.5,
    "voiceId": "<string>",
    "companyPhoneNumberId": "<string>",
    "metadata": {}
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    message: 'Screen senior backend devs. Ask about Go and Postgres, check notice period and salary expectation, then hand off to a recruiter if they\'re a strong fit.',
    type: 'PHONE',
    name: 'Senior Developer Phone Screen',
    duration: 90.5,
    voiceId: '<string>',
    companyPhoneNumberId: '<string>',
    metadata: {}
  })
};

fetch('https://api.instaview.sk/agents/composer', 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.instaview.sk/agents/composer",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'message' => 'Screen senior backend devs. Ask about Go and Postgres, check notice period and salary expectation, then hand off to a recruiter if they\'re a strong fit.',
    'type' => 'PHONE',
    'name' => 'Senior Developer Phone Screen',
    'duration' => 90.5,
    'voiceId' => '<string>',
    'companyPhoneNumberId' => '<string>',
    'metadata' => [
        
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "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.instaview.sk/agents/composer"

	payload := strings.NewReader("{\n  \"message\": \"Screen senior backend devs. Ask about Go and Postgres, check notice period and salary expectation, then hand off to a recruiter if they're a strong fit.\",\n  \"type\": \"PHONE\",\n  \"name\": \"Senior Developer Phone Screen\",\n  \"duration\": 90.5,\n  \"voiceId\": \"<string>\",\n  \"companyPhoneNumberId\": \"<string>\",\n  \"metadata\": {}\n}")

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

	req.Header.Add("Authorization", "Bearer <token>")
	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.post("https://api.instaview.sk/agents/composer")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"message\": \"Screen senior backend devs. Ask about Go and Postgres, check notice period and salary expectation, then hand off to a recruiter if they're a strong fit.\",\n  \"type\": \"PHONE\",\n  \"name\": \"Senior Developer Phone Screen\",\n  \"duration\": 90.5,\n  \"voiceId\": \"<string>\",\n  \"companyPhoneNumberId\": \"<string>\",\n  \"metadata\": {}\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.instaview.sk/agents/composer")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"message\": \"Screen senior backend devs. Ask about Go and Postgres, check notice period and salary expectation, then hand off to a recruiter if they're a strong fit.\",\n  \"type\": \"PHONE\",\n  \"name\": \"Senior Developer Phone Screen\",\n  \"duration\": 90.5,\n  \"voiceId\": \"<string>\",\n  \"companyPhoneNumberId\": \"<string>\",\n  \"metadata\": {}\n}"

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

{
  "sessionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "agent": {
    "type": "ONLINE",
    "flow": {
      "firstMessage": {
        "type": "first_message",
        "text": "Hi {{contact.firstName}}, do you have two minutes?",
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "label": "Qualify budget"
      },
      "sections": [
        {
          "type": "sequential",
          "prompt": "Introduce yourself and explain why you are calling.",
          "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "label": "Qualify budget"
        }
      ],
      "lastMessage": {
        "type": "last_message",
        "text": "Thanks for your time — have a great day!",
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "label": "Qualify budget"
      },
      "schemaVersion": "1.0.0"
    },
    "name": "Senior Developer Phone Screen",
    "language": "EN",
    "duration": 123,
    "voiceId": "<string>",
    "backgroundSound": "OFFICE",
    "companyPhoneNumberId": "<string>",
    "metadata": {},
    "overrides": {
      "companyName": "Acme Manufacturing",
      "companyDescription": "Acme makes industrial fasteners and employs 400 people across Slovakia."
    },
    "guardrails": {
      "rules": [
        "Never quote a price",
        "Never promise a delivery date"
      ]
    },
    "contextConfig": {
      "role": "an account executive for Acme",
      "communicationStyle": "concise and direct",
      "callToAction": "book a 30-minute demo"
    },
    "analyticsConfig": {
      "extractionTargets": [
        {
          "label": "Budget confirmed",
          "type": "bool",
          "key": "budget_confirmed",
          "enumValues": [
            "hot",
            "warm",
            "cold"
          ],
          "ideal": "A confirmed budget of at least 10k",
          "importance": "PREFERRED",
          "weight": 40
        }
      ],
      "scoringCriteria": [
        {
          "label": "Handled objections",
          "description": "Acknowledged the objection and answered it with a concrete example",
          "key": "handled_objections",
          "importance": "PREFERRED",
          "weight": 40
        }
      ],
      "outcomes": [
        {
          "label": "Meeting booked",
          "description": "The contact agreed to a specific date and time",
          "key": "meeting_booked"
        }
      ],
      "outputTags": [
        {
          "label": "Needs follow-up",
          "key": "needs_followup",
          "description": "The contact asked to be called back"
        }
      ],
      "capture": {
        "recording": true,
        "transcript": true,
        "summary": true,
        "qa": true,
        "evaluation": true,
        "sentiment": true
      }
    }
  },
  "message": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "role": "user",
    "content": "Your agent opens by introducing itself and confirming it's speaking with the right person. It then works through Go and Postgres experience…",
    "createdAt": "2023-11-07T05:31:56Z",
    "changes": [
      "Added a relocation question",
      "Set the language to Slovak"
    ]
  },
  "expiresAt": "2023-11-07T05:31:56Z"
}

{
  "statusCode": 422,
  "message": "Invalid conversation flow.",
  "errors": [
    {
      "code": "UNKNOWN_BLOCK_TYPE",
      "message": "Unknown block type: teleport.",
      "path": "sections[2].branches[0].blocks[1]"
    }
  ],
  "traceId": "6a707aee000000000c1e285eefed9980"
}

Describe the agent you want in plain language and get back the agent InstaView would build for you — the whole conversation, ready to create.

This does not create an agent. Nothing appears in your agent list, nothing can be called, and nothing is billable until you separately post the result to POST /agents. The 201 returned here created a composer session, not an agent.

That is the point of this endpoint: you can put “here is the agent I’d build for you” in front of a person, let them read it, change their mind twice, and only then create anything.

The shortest useful call

POST /agents/composer
{
  "type": "PHONE",
  "message": "Screen senior backend devs. Ask about Go and Postgres, check notice period and salary expectation, then hand off to a recruiter if they're a strong fit."
}

{
  "sessionId": "9f8c1d2e-4b7a-4c3d-9e1f-2a5b6c7d8e90",
  "agent": {
    "name": "Senior Backend Phone Screen",
    "type": "PHONE",
    "language": "EN",
    "flow": { "firstMessage": { "…": "…" }, "sections": [], "lastMessage": { "…": "…" } },
    "contextConfig": { "…": "…" },
    "analyticsConfig": { "…": "…" }
  },
  "message": {
    "id": "…",
    "role": "assistant",
    "content": "Your agent opens by introducing itself and confirming it's speaking with the right person. It then works through Go and Postgres experience, asks about notice period and salary expectation, and transfers strong candidates to a recruiter. Anyone who isn't a fit gets a polite close.",
    "changes": ["Named it Senior Backend Phone Screen", "Set the language to EN", "Added Skills deep-dive"],
    "createdAt": "2026-08-18T10:15:00.000Z"
  },
  "expiresAt": "2026-09-17T10:15:00.000Z"
}

Two fields are required: your message, and the type of agent to design.

type is required and cannot change later. The channel decides which conversation steps are legal at all — a transfer to a person exists only on PHONE — so it has to be known before the agent is designed rather than guessed from your brief.

Everything else is optional and, if you send it, wins over what the composer chose — on this turn and on every later one. That is what name, language, duration, voiceId, backgroundSound, companyPhoneNumberId and metadata are for: pin the things you already know, and let the composer decide the rest.

You do not send a flow. flow, focus, guardrails, contextConfig and analyticsConfig are what the composer writes for you, and sending any of them is rejected with a 422 naming which. If you already have a flow, you do not need the composer — post it straight to POST /agents.

The accompanying message

message.content is a plain-language description of the agent, in at most ten sentences: what it opens with, what it asks about, what it decides, and how it ends. It is written for a person, not for a parser — it is the text to show next to a “create this agent” button. message.changes is a short list of labels for what the composer did. On the first turn it describes what it built; on later turns, what changed.

What to do with the preview

agent is a body POST /agents accepts verbatim — no ids, no schemaVersion, and a conditional’s fallthrough already named by defaultBranch. Nothing to strip, nothing to fix up.

Change something first

Send another message to the session — “also ask about relocation”, “make it Slovak”.

Create it

Post the agent object, or just { "composerSessionId": "…" }.

The simplest way to create it is to hand back the session id and let us build exactly what you were shown:

POST /agents
{ "composerSessionId": "9f8c1d2e-4b7a-4c3d-9e1f-2a5b6c7d8e90" }

Send fields alongside it to change your mind at the last moment — { "composerSessionId": "…", "name": "Backend Screen v2" } creates the previewed agent under a different name.

The conversation follows the agent. However you create it, the messages that designed it are attached to the new agent, so opening it in InstaView shows how it was built — and someone can carry on editing it there by hand.

Sessions expire

A session lives 30 days. After that, a preview nobody accepted is deleted along with its conversation; expiresAt on every response tells you when. Creating the agent ends the clock — a session that became an agent is kept.

Rate limits

Every call here designs an agent with a language model, so these routes carry their own limit on top of your key’s usual allowance: 6 per minute and 60 per hour for this endpoint, 10 per minute and 120 per hour for refining. Exceeding it is a 429.

Errors

Status	When
`400`	`message` or `type` missing, malformed, or over 8,000 characters — or you sent `flow`, `focus`, `guardrails`, `contextConfig` or `analyticsConfig`, which the composer writes (`property flow should not exist`)
`404`	The composer is not enabled for your account
`422`	The brief could not be turned into a valid agent, or you sent `flow` / `focus` / a config object
`429`	Composer rate limit reached
`503`	The model was unavailable or timed out — nothing was created

A 422 here means no session was created. Rephrase or add detail and call again.

Designing an agent takes a few seconds — it is a language-model call, not a database write, and a long brief takes longer than a short one. Allow up to two minutes on your client before you give up on the request; a short brief plus a couple of refinements is both quicker and easier to review than one page-long brief.

Authorizations

Authorization

string

header

required

API key for authentication using Bearer scheme

Query Parameters

companyId

string

Required for ATS API keys to specify which company to access. Ignored for standard company API keys.

Body

application/json

message

string

required

What the agent should do, in plain language. The composer designs the whole conversation from this.

Maximum string length: 8000

Example:

"Screen senior backend devs. Ask about Go and Postgres, check notice period and salary expectation, then hand off to a recruiter if they're a strong fit."

type

enum<string>

required

The channel the agent will run on. Required, and fixed for the life of the session: it decides which conversation steps are available at all — a transfer to a person exists only on PHONE.

Available options:

ONLINE,

PHONE

Example:

"PHONE"

name

string

Name for the agent. Optional — the composer proposes one from your brief. Anything you send here wins, and keeps winning on later turns.

Required string length: 3 - 100

Example:

"Senior Developer Phone Screen"

language

enum<string>

Language of the conversation. When omitted, the composer follows the language of your brief.

Available options:

EN,

SK,

CS

duration

number

Target call length in minutes.

Required range: 1 <= x <= 180

voiceId

string

Voice for the agent.

backgroundSound

enum<string>

Ambient background sound.

Available options:

OFFICE,

OFF

companyPhoneNumberId

string

The number this agent should call from. PHONE agents only.

metadata

object

Custom metadata carried through to the agent you create from this session.

Response

The composer session, the agent it would create, and the composer's reply.

sessionId

string<uuid>

required

The session to send follow-up messages to, and to create the agent from.

agent

object

required

The agent the composer would build. There is no id: this agent does not exist yet. Post this object to POST /agents to create it — it is accepted verbatim, with no ids or schemaVersion to strip first.

Show child attributes

message

object

required

Show child attributes

expiresAt

string<date-time>

required

When this session is deleted if you never create the agent. Sessions live 30 days.

Overview

Agents

Agent Knowledge Base

Jobs

Candidates

Companies

Interviews

Billing

Voice

Webhooks

Sourcing

Phone Numbers

The shortest useful call

The accompanying message

What to do with the preview

Change something first

Create it

Sessions expire

Rate limits

Errors

Authorizations

Query Parameters

Body

Response

​The shortest useful call

​The accompanying message

​What to do with the preview

Change something first

Create it

​Sessions expire

​Rate limits

​Errors

Authorizations

Query Parameters

Body

Response

The shortest useful call

The accompanying message

What to do with the preview

Sessions expire

Rate limits

Errors