Roark Metric Policy API
The Metric Policy API from Roark — 2 operation(s) for metric policy.
The Metric Policy API from Roark — 2 operation(s) for metric policy.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/roark:roark-metric-policy-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Roark Analytics Metric Policy API
description: The Roark Analytics API gives you access to the same API that powers the award winning Roark Analytics platform.
version: 1.0.0
servers:
- description: Production
url: https://api.roark.ai
security:
- Bearer: []
tags:
- name: Metric Policy
paths:
/v1/metric/policies:
get:
responses:
'200':
description: Paginated list of metric policies
content:
application/json:
schema:
$ref: '#/components/schemas/GetMetricPoliciesResponse'
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Authentication error
example:
type: authentication
code: unauthorized
message: Authentication required
description: Unauthorized
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Permission error
example:
type: forbidden
code: permission_denied
message: You do not have permission to access this resource
description: Forbidden
'429':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Rate limit error
example:
type: rate_limit
code: too_many_requests
message: Rate limit exceeded
description: Too Many Requests
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Server error
example:
type: internal
code: internal_error
message: Internal server error
description: Internal Server Error
operationId: getV1MetricPolicies
tags:
- Metric Policy
summary: List metric policies
description: Returns a paginated list of metric policies for the project, including system policies.
parameters:
- in: query
name: limit
schema:
type: integer
minimum: 1
maximum: 50
default: 20
description: 'Maximum number of policies to return (default: 20, max: 50)'
example: 20
- in: query
name: after
schema:
type: string
description: Cursor for pagination - use the nextCursor value from a previous response
- in: query
name: status
schema:
type: string
enum:
- ACTIVE
- INACTIVE
description: Filter by policy status
post:
responses:
'201':
description: The created metric policy
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/MetricPolicyResponse'
required:
- data
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Validation error
example:
type: validation
code: invalid_parameter
message: The request was invalid
param: email
description: Bad Request
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Authentication error
example:
type: authentication
code: unauthorized
message: Authentication required
description: Unauthorized
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Permission error
example:
type: forbidden
code: permission_denied
message: You do not have permission to access this resource
description: Forbidden
'429':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Rate limit error
example:
type: rate_limit
code: too_many_requests
message: Rate limit exceeded
description: Too Many Requests
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Server error
example:
type: internal
code: internal_error
message: Internal server error
description: Internal Server Error
operationId: postV1MetricPolicies
tags:
- Metric Policy
summary: Create a metric policy
description: Creates a new metric policy. Policies define which metrics to collect and under what conditions.
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateMetricPolicyInput'
/v1/metric/policies/{policyId}:
get:
responses:
'200':
description: The requested metric policy
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/MetricPolicyResponse'
required:
- data
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Authentication error
example:
type: authentication
code: unauthorized
message: Authentication required
description: Unauthorized
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Not found error
example:
type: not_found
code: resource_not_found
message: The requested resource could not be found
description: Not Found
'429':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Rate limit error
example:
type: rate_limit
code: too_many_requests
message: Rate limit exceeded
description: Too Many Requests
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Server error
example:
type: internal
code: internal_error
message: Internal server error
description: Internal Server Error
operationId: getV1MetricPoliciesByPolicyId
tags:
- Metric Policy
summary: Get metric policy by ID
description: Returns a specific metric policy with its conditions and metrics.
parameters:
- name: policyId
in: path
required: true
description: The ID of the metric policy to retrieve
schema:
type: string
format: uuid
put:
responses:
'200':
description: The updated metric policy
content:
application/json:
schema:
type: object
properties:
data:
$ref: '#/components/schemas/MetricPolicyResponse'
required:
- data
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Validation error
example:
type: validation
code: invalid_parameter
message: The request was invalid
param: email
description: Bad Request
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Authentication error
example:
type: authentication
code: unauthorized
message: Authentication required
description: Unauthorized
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Not found error
example:
type: not_found
code: resource_not_found
message: The requested resource could not be found
description: Not Found
'429':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Rate limit error
example:
type: rate_limit
code: too_many_requests
message: Rate limit exceeded
description: Too Many Requests
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Server error
example:
type: internal
code: internal_error
message: Internal server error
description: Internal Server Error
operationId: putV1MetricPoliciesByPolicyId
tags:
- Metric Policy
summary: Update a metric policy
description: Updates an existing metric policy. System policies cannot be modified.
parameters:
- name: policyId
in: path
required: true
description: The ID of the metric policy to update
schema:
type: string
format: uuid
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateMetricPolicyInput'
delete:
responses:
'200':
description: Metric policy deleted successfully
content:
application/json:
schema:
type: object
properties:
data:
type: object
properties:
deleted:
type: boolean
description: Whether the policy was deleted
required:
- deleted
required:
- data
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Authentication error
example:
type: authentication
code: unauthorized
message: Authentication required
description: Unauthorized
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Not found error
example:
type: not_found
code: resource_not_found
message: The requested resource could not be found
description: Not Found
'429':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Rate limit error
example:
type: rate_limit
code: too_many_requests
message: Rate limit exceeded
description: Too Many Requests
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Server error
example:
type: internal
code: internal_error
message: Internal server error
description: Internal Server Error
operationId: deleteV1MetricPoliciesByPolicyId
tags:
- Metric Policy
summary: Delete a metric policy
description: Soft-deletes a metric policy. System policies cannot be deleted.
parameters:
- name: policyId
in: path
required: true
description: The ID of the metric policy to delete
schema:
type: string
format: uuid
components:
schemas:
PolicyMetricSettings:
type: object
properties:
verifiedProperties:
type: array
items:
type: string
minLength: 1
maxLength: 200
maxItems: 50
description: 'Property Verification metrics: the conversation properties to check against the transcript. Empty or omitted checks every custom property.'
excludedPhrases:
type: array
items:
type: string
minLength: 1
maxLength: 200
maxItems: 50
description: 'Voice consistency metrics: phrases whose agent lines are not judged, such as a recorded prompt in a different voice.'
voicemailScript:
type: string
minLength: 1
maxLength: 4000
description: 'Voicemail metrics: the message the agent is expected to leave on voicemail.'
screeningBrief:
type: string
minLength: 1
maxLength: 4000
description: 'Call screening metrics: what the agent should say when a screener asks who is calling and why.'
toolDefinitionIds:
type: array
items:
type: string
format: uuid
description: 'Tool invocation metrics: the tool definitions to score. Empty or omitted scores every tool the agent has.'
knowledgeBaseDocumentIds:
type: array
items:
type: string
format: uuid
description: 'Knowledge grounding metrics: the knowledge base documents to ground against, in priority order. Empty or omitted uses every knowledge base in the project.'
additionalProperties: false
description: 'The metric''s per-collector setting. A metric takes at most one field, and which one depends on the metric: verifiedProperties for Property Verification, excludedPhrases for voice consistency, voicemailScript for voicemail, screeningBrief for call screening, toolDefinitionIds for tool invocation, knowledgeBaseDocumentIds for knowledge grounding. A field the metric doesn''t take is rejected with a 400.'
UpdateMetricPolicyInput:
type: object
properties:
name:
type: string
minLength: 1
description: Name of the metric policy
status:
type: string
enum:
- ACTIVE
- INACTIVE
description: Status of the policy
conditions:
type: array
items:
type: object
properties:
conditions:
type: array
items:
type: object
properties:
conditionType:
type: string
enum:
- AGENT
- CALL_SOURCE
- CALL_PROPERTY
- INTEGRATION
description: 'Type of condition: AGENT (match by agent ID), CALL_SOURCE (match by source e.g. VAPI, RETELL), CALL_PROPERTY (match by call property key/value)'
conditionKey:
type: string
description: 'Key to match against. For AGENT: the agent ID. For CALL_SOURCE: the source name. For CALL_PROPERTY: the property key.'
conditionOperator:
type:
- string
- 'null'
enum:
- EQUALS
- NOT_EQUALS
- CONTAINS
- STARTS_WITH
- GREATER_THAN
- LESS_THAN
- GREATER_THAN_OR_EQUALS
- LESS_THAN_OR_EQUALS
description: Comparison operator. Required for CALL_PROPERTY conditions.
conditionValue:
type:
- string
- 'null'
description: Value to compare against. Required for CALL_PROPERTY conditions.
required:
- conditionType
- conditionKey
required:
- conditions
description: Condition groups. Omit to keep existing, provide empty array to remove all conditions.
metrics:
type: array
items:
type: object
properties:
id:
type: string
format: uuid
description: The metric definition to collect
settings:
oneOf:
- $ref: '#/components/schemas/PolicyMetricSettings'
- type: 'null'
description: Optional. Omit, or send null, to collect the metric with its default (every property, every tool, no excluded phrases). Null is what a read returns for a metric on its default, so a fetched metrics list can be sent back as is.
required:
- id
minItems: 1
description: 'Metric definitions to collect when this policy matches. Replaces the policy''s whole metric list: a metric sent without settings goes back to its default, so resend a metric''s settings to keep them. Omit to keep the current metrics.'
description: Input for updating an existing metric policy
ErrorResponse:
type: object
properties:
type:
type: string
enum:
- validation
- authentication
- forbidden
- not_found
- conflict
- payment_required
- rate_limit
- internal
description: The error type category
examples:
- validation
- authentication
code:
type: string
description: Machine-readable error code identifier
examples:
- invalid_parameter
- missing_required_field
- unauthorized
message:
type: string
description: Human-readable error message
examples:
- The request was invalid
- Authentication required
param:
type: string
description: The parameter that caused the error (if applicable)
examples:
- email
- user_id
details:
description: Additional error context information
required:
- type
- code
- message
CreateMetricPolicyInput:
type: object
properties:
name:
type: string
minLength: 1
description: Name of the metric policy
example: Evaluate all inbound calls
status:
type: string
enum:
- ACTIVE
- INACTIVE
default: ACTIVE
description: 'Status of the policy (default: ACTIVE)'
example: ACTIVE
modality:
type: string
enum:
- call
- chat
description: Modality this policy targets. A policy fires for exactly one modality and can only reference metrics that support that modality.
example: call
conditions:
type: array
items:
type: object
properties:
conditions:
type: array
items:
type: object
properties:
conditionType:
type: string
enum:
- AGENT
- CALL_SOURCE
- CALL_PROPERTY
- INTEGRATION
description: 'Type of condition: AGENT (match by agent ID), CALL_SOURCE (match by source e.g. VAPI, RETELL), CALL_PROPERTY (match by call property key/value)'
conditionKey:
type: string
description: 'Key to match against. For AGENT: the agent ID. For CALL_SOURCE: the source name. For CALL_PROPERTY: the property key.'
conditionOperator:
type:
- string
- 'null'
enum:
- EQUALS
- NOT_EQUALS
- CONTAINS
- STARTS_WITH
- GREATER_THAN
- LESS_THAN
- GREATER_THAN_OR_EQUALS
- LESS_THAN_OR_EQUALS
description: Comparison operator. Required for CALL_PROPERTY conditions.
conditionValue:
type:
- string
- 'null'
description: Value to compare against. Required for CALL_PROPERTY conditions.
required:
- conditionType
- conditionKey
required:
- conditions
description: Condition groups. Omit to match all calls.
metrics:
type: array
items:
type: object
properties:
id:
type: string
format: uuid
description: The metric definition to collect
settings:
oneOf:
- $ref: '#/components/schemas/PolicyMetricSettings'
- type: 'null'
description: Optional. Omit, or send null, to collect the metric with its default (every property, every tool, no excluded phrases). Null is what a read returns for a metric on its default, so a fetched metrics list can be sent back as is.
required:
- id
minItems: 1
description: Metric definitions to collect when this policy matches, each with an optional setting
required:
- name
- modality
- metrics
description: Input for creating a new metric policy
GetMetricPoliciesResponse:
type: object
properties:
data:
type: array
items:
$ref: '#/components/schemas/MetricPolicyResponse'
pagination:
type: object
properties:
total:
type: number
description: Total number of items
hasMore:
type: boolean
description: Whether there are more items to fetch
nextCursor:
type:
- string
- 'null'
description: Cursor for the next page of items
required:
- total
- hasMore
- nextCursor
required:
- data
- pagination
description: Paginated list of metric policies
MetricPolicyResponse:
type: object
properties:
id:
type: string
format: uuid
description: Unique identifier of the metric policy
name:
type: string
description: Name of the metric policy
type:
type: string
enum:
- SYSTEM
- USER
description: Type of the metric policy (SYSTEM or USER)
status:
type: string
enum:
- ACTIVE
- INACTIVE
description: Status of the metric policy (ACTIVE or INACTIVE)
conditions:
type:
- array
- 'null'
items:
type: object
properties:
conditions:
type: array
items:
type: object
properties:
conditionType:
type: string
enum:
- AGENT
- CALL_SOURCE
- CALL_PROPERTY
- INTEGRATION
description: 'Type of condition: AGENT (match by agent ID), CALL_SOURCE (match by source e.g. VAPI, RETELL), CALL_PROPERTY (match by call property key/value)'
conditionKey:
type: string
description: 'Key to match against. For AGENT: the agent ID. For CALL_SOURCE: the source name. For CALL_PROPERTY: the property key.'
conditionOperator:
type:
- string
- 'null'
enum:
- EQUALS
- NOT_EQUALS
- CONTAINS
- STARTS_WITH
- GREATER_THAN
- LESS_THAN
- GREATER_THAN_OR_EQUALS
- LESS_THAN_OR_EQUALS
description: Comparison operator. Required for CALL_PROPERTY conditions.
conditionValue:
type:
- string
- 'null'
description: Value to compare against. Required for CALL_PROPERTY conditions.
required:
- conditionType
- conditionKey
- conditionOperator
- conditionValue
required:
- conditions
description: Condition groups for this policy. Null means the policy matches all calls.
metrics:
type: array
items:
type: object
properties:
id:
type: string
format: uuid
settings:
oneOf:
- $ref: '#/components/schemas/PolicyMetricSettings'
- type: 'null'
description: The metric's per-collector setting, or null when it runs with its default
required:
- id
- settings
description: Metric definitions associated with this policy
createdAt:
type: string
description: When the policy was created
updatedAt:
type: string
description: When the policy was last updated
required:
- id
- name
- type
- status
- conditions
- metrics
- createdAt
- updatedAt
description: A metric policy defining when metrics should be collected
securitySchemes:
Bearer:
type: http
scheme: bearer
bearerFormat: JWT