Retrieve a copilot profile

GET

/copilot_profiles/{id}

import MoreVoice from "@morevoice/sdk";

const mv = new MoreVoice(); // MOREVOICE_API_KEY from the environment

const copilotProfile = await mv.copilotProfiles.retrieve("cop_7Hk2Lm9Qp");
console.log(copilotProfile);

Returns the CopilotProfile object. Answers 404 with the code resource_missing when nothing has this ID in this organisation and mode.

Try it in the API playground with a test-mode key.

Authorizations

bearerAuth

Parameters

Path Parameters

required

string

<= 200 characters /^cop_[0-9A-Za-z]+$/

A copilot profile ID (cop_…).

Header Parameters

MoreVoice-Version

string

/^\d{4}-\d{2}-\d{2}$/

The API version to use for this request. Defaults to the version the API key is pinned to.

Example

2026-11-01

Responses

200

application/json

How the real-time agent copilot coaches one kind of call: stages, objections, knowledge, fields, compliance, alerts and the QA rubric.

object

alerts

required

Array<object>

<= 100 items

object

key

required

Your stable identifier of the item.

string

>= 1 characters <= 64 characters

kind

required

string

Allowed values: keyword sentiment silence monologue talk_ratio long_call escalation

label

required

string

<= 500 characters

message

required

string

<= 1000 characters

notify_supervisor

required

Also raise it on the supervisor board.

boolean

phrases

required

Keyword / escalation: customer phrases.

Array<string>

<= 200 items

severity

required

string

Allowed values: info warn critical

threshold

required

Sentiment: below this (−1…1); silence / monologue: seconds; talk_ratio: agent share; long_call: minutes.

number

coaching

required

object

monologue_seconds_max

required

Continuous agent speech before “ask a question”.

number

>= 5

silence_seconds_max

required

Dead air before a nudge.

number

>= 2

talk_ratio_max

required

Agent share of talk time above which to nudge (0–1).

number

<= 1

wpm_max

required

number

>= 60

wpm_min

required

number

company

required

Who the agent represents.

string

<= 500 characters

compliance

required

object

forbidden_phrases

required

Array<object>

<= 300 items

object

instead

required

Safer wording shown on the alert.

string

<= 1000 characters

phrase

required

string

<= 500 characters

reason

required

string

<= 1000 characters

severity

required

string

Allowed values: info warn critical

required_disclosures

required

Array<object>

<= 50 items

object

before_stage_key

required

…or before leaving this stage.

string

<= 64 characters

deadline_seconds

required

Alert when not said this long into the call (0: before the call ends).

number

key

required

Your stable identifier of the item.

string

>= 1 characters <= 64 characters

label

required

string

<= 500 characters

phrases

required

Array<string>

<= 200 items

script

required

The exact wording to read out if it was missed.

string

<= 4000 characters

created

required

An ISO-8601 timestamp in UTC.

string format: date-time

fields

required

Details the copilot picks out of the conversation.

Array<object>

<= 100 items

object

hint

required

A hint for the extractor.

string

<= 500 characters

key

required

Your stable identifier of the item.

string

>= 1 characters <= 64 characters

label

required

string

<= 500 characters

options

required

Array<string>

<= 200 items

pattern

required

string

<= 400 characters

required

required

boolean

type

required

string

Allowed values: text number money phone email date enum boolean id

goal

required

What the call should achieve.

string

<= 4000 characters

required

The profile’s ID.

string

/^cop_[0-9A-Za-z]+$/

required

object

document_ids

required

Knowledge-base documents the profile may use (empty: all).

Array<string>

<= 500 items

links

required

Reference links shown to the agent.

Array<object>

<= 50 items

object

label

required

string

<= 200 characters

url

required

string

<= 2000 characters

min_score

required

Minimum confidence (0–1) to show a knowledge card unasked.

number

<= 1

language

required

The calls’ language (he, en, …).

string

<= 10 characters

livemode

required

true in live mode, false in test mode.

boolean

model

required

object

api

required

string

Allowed values: chat responses

deep_path

required

False: the fast path only (no model calls).

boolean

fallback_model

required

string

<= 80 characters

max_calls_per_minute

required

Model calls per minute per call.

integer

<= 60

model

required

string

<= 80 characters

objection_similarity

required

Meaning-based objection match threshold (cosine).

number

<= 1

priority

required

Priority processing: steadier, lower latency, higher token price.

boolean

speculative

required

Start on stable interim text, before the utterance is final.

boolean

temperature

required

number

<= 2

name

required

string

object

required

string

Allowed value: copilot_profile

objections

required

The objection library.

Array<object>

<= 300 items

object

examples

required

Paraphrases for the meaning-based match.

Array<string>

<= 200 items

follow_up

required

string

<= 1000 characters

kb_query

required

A knowledge-base query whose facts are attached to the card.

string

<= 500 characters

key

required

Your stable identifier of the item.

string

>= 1 characters <= 64 characters

label

required

string

<= 500 characters

response

required

The recommended answer shown on the card.

string

<= 4000 characters

triggers

required

Customer phrases that fire it at once.

Array<string>

<= 200 items

product

required

string

<= 2000 characters

qa_rubric

required

The QA rubric this profile’s calls are scored against (empty: the organisation’s rubric).

Array<object>

<= 50 items

object

description

required

string

<= 2000 characters

key

required

Your stable identifier of the item.

string

>= 1 characters <= 64 characters

label

required

string

<= 500 characters

weight

required

Relative importance on one 0–100 scale (points out of 100); only the ratios count.

number

<= 100

script

required

object

flow_id

required

Any of:

string
null

A flow ID (prefix flow_).

string

/^flow_[0-9A-Za-z]+$/

version

required

Any of:

string
integer

string

Allowed value: published

stages

required

The call’s stages, each with a checklist (used when no script flow is set).

Array<object>

<= 50 items

object

checklist

required

Array<object>

<= 100 items

object

ask

required

The question the copilot suggests while it is open.

string

<= 1000 characters

key

required

Your stable identifier of the item.

string

>= 1 characters <= 64 characters

label

required

string

<= 500 characters

phrases

required

Agent phrases that tick it automatically; a trailing * matches a prefix.

Array<string>

<= 200 items

required

required

boolean

goal

required

string

<= 2000 characters

key

required

Your stable identifier of the item.

string

>= 1 characters <= 64 characters

label

required

string

<= 500 characters

template_id

required

The template it was created from.

string | null

tone

required

How the agent should sound.

string

<= 2000 characters

updated

required

An ISO-8601 timestamp in UTC.

string format: date-time

version

required

Goes up on every change.

integer

>= -9007199254740991 <= 9007199254740991

Example

{
  "alerts": [
    {
      "key": "escalation",
      "kind": "escalation",
      "label": "Asks for a manager",
      "message": "Acknowledge and offer a solution.",
      "notify_supervisor": true,
      "phrases": [
        "manager"
      ],
      "severity": "critical",
      "threshold": 0
    }
  ],
  "coaching": {
    "monologue_seconds_max": 40,
    "silence_seconds_max": 7,
    "talk_ratio_max": 0.65,
    "wpm_max": 175,
    "wpm_min": 0
  },
  "company": "Acme",
  "compliance": {
    "forbidden_phrases": [
      {
        "instead": "In most cases",
        "phrase": "guaranteed",
        "reason": "No guarantees",
        "severity": "warn"
      }
    ],
    "required_disclosures": []
  },
  "created": "2026-11-03T09:14:22.000Z",
  "fields": [
    {
      "hint": "",
      "key": "budget",
      "label": "Monthly budget",
      "options": [],
      "pattern": "",
      "required": false,
      "type": "money"
    }
  ],
  "goal": "Book a demo or a clear next step.",
  "id": "cop_8Ps2Ux5Zc7Eh0Jm3Or6Tw9",
  "kb": {
    "document_ids": [
      "kbd_6Nq0Sv3Xa5Cf8Hk1Mp4Rt7"
    ],
    "links": [],
    "min_score": 0.35
  },
  "language": "en",
  "livemode": true,
  "model": {
    "api": "chat",
    "deep_path": true,
    "fallback_model": "gpt-4.1-nano",
    "max_calls_per_minute": 12,
    "model": "gpt-4.1-mini",
    "objection_similarity": 0.72,
    "priority": true,
    "speculative": true,
    "temperature": 0.3
  },
  "name": "Outbound sales",
  "object": "copilot_profile",
  "objections": [
    {
      "examples": [
        "it costs too much"
      ],
      "follow_up": "What do you pay now?",
      "kb_query": "price list",
      "key": "price",
      "label": "Too expensive",
      "response": "Compare it with what downtime costs you today.",
      "triggers": [
        "too expensive"
      ]
    }
  ],
  "product": "Acme Cloud PBX",
  "qa_rubric": [
    {
      "description": "Asked open questions first.",
      "key": "discovery",
      "label": "Discovery",
      "weight": 60
    },
    {
      "description": "Agreed a dated next step.",
      "key": "close",
      "label": "Next step",
      "weight": 40
    }
  ],
  "script": {
    "flow_id": null,
    "version": "published"
  },
  "stages": [
    {
      "checklist": [
        {
          "ask": "",
          "key": "recorded",
          "label": "Say the call is recorded",
          "phrases": [
            "this call is recorded"
          ],
          "required": true
        }
      ],
      "goal": "Introduce yourself and ask for two minutes",
      "key": "opening",
      "label": "Opening"
    }
  ],
  "template_id": "sales-outbound",
  "tone": "Warm, confident, never pushy.",
  "updated": "2026-11-03T09:14:22.000Z",
  "version": 4
}

400

The request is invalid: a parameter is missing, malformed or unknown, or the version header is unknown.

application/json

Every /v1 error.

object

error

required

object

code

required

A stable, machine-readable code from the error-code catalogue.

string

details

Structured context, e.g. required_scope or the compliance verdict.

object

key

additional properties

doc_url

required

A link to the documentation of this code.

string

message

required

A human-readable explanation. Do not parse it.

string

param

The request parameter the error relates to, e.g. to or metadata[order_id].

string

request_id

required

The X-Request-Id of this request. Quote it when you contact support.

string

type

required

The category of the error.

string

Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error compliance_error idempotency_error api_error

Example

{
  "error": {
    "code": "parameter_missing",
    "doc_url": "https://docs.morevoice.ai/api/errors#parameter-missing",
    "message": "Missing required parameter: to.",
    "param": "to",
    "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ",
    "type": "invalid_request_error"
  }
}

Headers

X-Request-Id

string

The request’s ID (req_…). Quote it when you contact support.

401

No valid API key was sent.

application/json

Every /v1 error.

object

error

required

object

code

required

A stable, machine-readable code from the error-code catalogue.

string

details

Structured context, e.g. required_scope or the compliance verdict.

object

key

additional properties

doc_url

required

A link to the documentation of this code.

string

message

required

A human-readable explanation. Do not parse it.

string

param

The request parameter the error relates to, e.g. to or metadata[order_id].

string

request_id

required

The X-Request-Id of this request. Quote it when you contact support.

string

type

required

The category of the error.

string

Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error compliance_error idempotency_error api_error

Example

{
  "error": {
    "code": "invalid_api_key",
    "doc_url": "https://docs.morevoice.ai/api/errors#invalid-api-key",
    "message": "Invalid API key.",
    "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ",
    "type": "authentication_error"
  }
}

Headers

X-Request-Id

string

The request’s ID (req_…). Quote it when you contact support.

403

The key may not do this (a missing scope, a plan limit, or a compliance block).

application/json

Every /v1 error.

object

error

required

object

code

required

A stable, machine-readable code from the error-code catalogue.

string

details

Structured context, e.g. required_scope or the compliance verdict.

object

key

additional properties

doc_url

required

A link to the documentation of this code.

string

message

required

A human-readable explanation. Do not parse it.

string

param

The request parameter the error relates to, e.g. to or metadata[order_id].

string

request_id

required

The X-Request-Id of this request. Quote it when you contact support.

string

type

required

The category of the error.

string

Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error compliance_error idempotency_error api_error

Example

{
  "error": {
    "code": "missing_scope",
    "doc_url": "https://docs.morevoice.ai/api/errors#missing-scope",
    "message": "This API key lacks the calls:write scope.",
    "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ",
    "type": "permission_error"
  }
}

Headers

X-Request-Id

string

The request’s ID (req_…). Quote it when you contact support.

404

No object with this ID exists in this organisation and mode.

application/json

Every /v1 error.

object

error

required

object

code

required

A stable, machine-readable code from the error-code catalogue.

string

details

Structured context, e.g. required_scope or the compliance verdict.

object

key

additional properties

doc_url

required

A link to the documentation of this code.

string

message

required

A human-readable explanation. Do not parse it.

string

param

The request parameter the error relates to, e.g. to or metadata[order_id].

string

request_id

required

The X-Request-Id of this request. Quote it when you contact support.

string

type

required

The category of the error.

string

Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error compliance_error idempotency_error api_error

Example

{
  "error": {
    "code": "resource_missing",
    "doc_url": "https://docs.morevoice.ai/api/errors#resource-missing",
    "message": "No such object: 'call_4Gk2'.",
    "param": "id",
    "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ",
    "type": "not_found"
  }
}

Headers

X-Request-Id

string

The request’s ID (req_…). Quote it when you contact support.

429

Too many requests, or no call capacity right now. Retry after the Retry-After delay.

application/json

Every /v1 error.

object

error

required

object

code

required

A stable, machine-readable code from the error-code catalogue.

string

details

Structured context, e.g. required_scope or the compliance verdict.

object

key

additional properties

doc_url

required

A link to the documentation of this code.

string

message

required

A human-readable explanation. Do not parse it.

string

param

The request parameter the error relates to, e.g. to or metadata[order_id].

string

request_id

required

The X-Request-Id of this request. Quote it when you contact support.

string

type

required

The category of the error.

string

Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error compliance_error idempotency_error api_error

Example

{
  "error": {
    "code": "rate_limited",
    "doc_url": "https://docs.morevoice.ai/api/errors#rate-limited",
    "message": "Too many requests. Retry after 1 second.",
    "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ",
    "type": "rate_limit_error"
  }
}

Headers

Retry-After

integer

Seconds to wait before retrying.

X-Request-Id

string

The request’s ID (req_…). Quote it when you contact support.

500

Something went wrong on MoreVoice’s side. Retry with the same Idempotency-Key.

application/json

Every /v1 error.

object

error

required

object

code

required

A stable, machine-readable code from the error-code catalogue.

string

details

Structured context, e.g. required_scope or the compliance verdict.

object

key

additional properties

doc_url

required

A link to the documentation of this code.

string

message

required

A human-readable explanation. Do not parse it.

string

param

The request parameter the error relates to, e.g. to or metadata[order_id].

string

request_id

required

The X-Request-Id of this request. Quote it when you contact support.

string

type

required

The category of the error.

string

Allowed values: invalid_request_error authentication_error permission_error not_found conflict rate_limit_error compliance_error idempotency_error api_error

Example

{
  "error": {
    "code": "internal_error",
    "doc_url": "https://docs.morevoice.ai/api/errors#internal-error",
    "message": "Something went wrong on MoreVoice's side.",
    "request_id": "req_7Hk2LmN9pQ4rS6tV8wX0yZ",
    "type": "api_error"
  }
}

Headers

X-Request-Id

string

The request’s ID (req_…). Quote it when you contact support.