{
"openapi": "3.0.0",
"info": {
"title": "Forestreet API",
"version": "1.0.0",
"description": "API documentation for Forestreet API"
},
"tags": [],
"servers": [
{
"url": "http://localhost:4000",
"description": "Local server"
},
{
"url": "https://rest-dev.forestreet.com",
"description": "Development server"
}
],
"security": [
{
"apiKeyAuth": []
},
{
"bearerAuth": []
},
{
"sessionIdQuery": []
}
],
"components": {
"securitySchemes": {
"apiKeyAuth": {
"type": "apiKey",
"in": "header",
"name": "x-api-key",
"description": "Pass a static API key for every request, provided by your customer support."
},
"bearerAuth": {
"type": "http",
"scheme": "bearer",
"description": "Bearer token authentication, using a sessionId generated by `GET /v2/auth/session`."
},
"sessionIdQuery": {
"type": "apiKey",
"in": "query",
"name": "sessionId",
"description": "Session ID passed as a query parameter for authentication, provided by `GET /v2/auth/session`."
}
},
"schemas": {},
"parameters": {}
},
"paths": {
"/v2/auth/sign-in": {
"post": {
"tags": ["Auth"],
"summary": "Sign in",
"description": "\n Sign in a user with email and password; upon success, authentication cookies are set\n in the browser.\n\n This is used by Forestreet's internal frontend application.\n ",
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"email": {
"type": "string",
"format": "email",
"description": "Email address of the user."
},
"password": {
"type": "string",
"minLength": 1,
"description": "Password of the user."
}
},
"required": ["email", "password"]
}
}
}
},
"responses": {
"200": {
"description": "User signed in successfully",
"headers": {
"Set-Cookie": {
"schema": {
"type": "string",
"description": "Authentication cookies set in the response headers."
},
"required": true,
"description": "Authentication cookies set in the response headers."
}
},
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"description": "Message from the server."
},
"accessToken": {
"type": "string",
"pattern": "^[A-Za-z0-9-_]+(?:\\.[A-Za-z0-9-_]+)+$",
"description": "Access token for the user."
},
"refreshToken": {
"type": "string",
"pattern": "^[A-Za-z0-9-_]+(?:\\.[A-Za-z0-9-_]+)+$",
"description": "Refresh token for the user."
},
"expiresIn": {
"type": "number",
"description": "Expires duration for the access token."
},
"expiresAt": {
"type": "number",
"description": "Expires timestamp for the access token."
}
},
"required": ["message", "accessToken", "refreshToken", "expiresIn", "expiresAt"]
}
}
}
},
"400": {
"description": "Bad Request - Invalid input",
"content": {
"application/json": {
"examples": {
"INVALID_INPUT": {
"value": {
"success": false,
"errorCode": "INVALID_INPUT",
"message": "Bad Request - Invalid input"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"401": {
"description": "Unauthorized - Invalid credentials, token or cookies",
"content": {
"application/json": {
"examples": {
"UNAUTHORISED": {
"value": {
"success": false,
"errorCode": "UNAUTHORISED",
"message": "Unauthorized - Invalid credentials, token or cookies"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
}
}
}
},
"/v2/auth/sign-out": {
"post": {
"tags": ["Auth"],
"summary": "Sign out",
"description": "Revoke the current bearer or cookie session and clear authentication cookies.",
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"nullable": true,
"properties": {
"refreshToken": {
"type": "string",
"pattern": "^[A-Za-z0-9-_]+(?:\\.[A-Za-z0-9-_]+)+$",
"description": "Refresh token to revoke when signing out."
}
}
}
}
}
},
"responses": {
"200": {
"description": "Sign out response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"description": "Message from the server."
}
},
"required": ["message"]
}
}
}
}
}
}
},
"/v2/auth/session": {
"get": {
"tags": ["Auth"],
"summary": "Get session ID",
"description": "\n Create new session using a valid API key, which will return a JWT token in the response.\n\n This allows API users to create a timed session from the backend, before passing the resultant\n JWT token to an unauthenticated frontend application. This prevents any risks of the API key\n being exposed to the frontend application.\n\n See also [the `PUT /v2/auth/session` endpoint](/api-reference/endpoints/auth/set-session-cookies).\n ",
"parameters": [
{
"schema": {
"type": "string",
"minLength": 1,
"description": "API key for authentication."
},
"required": true,
"description": "API key for authentication.",
"name": "x-api-key",
"in": "header"
}
],
"responses": {
"200": {
"description": "Session created successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"message": {
"type": "string",
"description": "Message from the server."
},
"accessToken": {
"type": "string",
"pattern": "^[A-Za-z0-9-_]+(?:\\.[A-Za-z0-9-_]+)+$",
"description": "Access token for the user."
},
"refreshToken": {
"type": "string",
"pattern": "^[A-Za-z0-9-_]+(?:\\.[A-Za-z0-9-_]+)+$",
"description": "Refresh token for the user."
},
"expiresIn": {
"type": "number",
"description": "Expires duration for the access token."
},
"expiresAt": {
"type": "number",
"description": "Expires timestamp for the access token."
}
},
"required": ["message", "accessToken", "refreshToken", "expiresIn", "expiresAt"]
}
}
}
},
"400": {
"description": "Bad Request - Invalid input",
"content": {
"application/json": {
"examples": {
"INVALID_INPUT": {
"value": {
"success": false,
"errorCode": "INVALID_INPUT",
"message": "Bad Request - Invalid input"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"401": {
"description": "Unauthorized - Invalid credentials, token or cookies",
"content": {
"application/json": {
"examples": {
"UNAUTHORISED": {
"value": {
"success": false,
"errorCode": "UNAUTHORISED",
"message": "Unauthorized - Invalid credentials, token or cookies"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
}
}
},
"put": {
"tags": ["Auth"],
"summary": "Set Session Cookies",
"description": "\n Using a JWT token and a checksum, this endpoint sets session cookies in the user's browser.\n\n This is typically used in iFrames where a client's backend generates a JWT Token using its API key,\n and the backend then asks the end user's browser to render an iFrame with the JWT Token embedded.\n The iFrame then calls this endpoint to set the cookies in the browser.\n\n The checksum is computed using HMAC with the tokens as input to ensure the tokens have not been tampered with.\n If the checksum does not match, an error is thrown indicating that the tokens have been tampered with.\n\n See also [the `GET /v2/auth/session` endpoint](/api-reference/endpoints/auth/get-session-id).\n\n You can use this endpoint to set the cookies in the iFrame, then redirect the user to the desired page\n using the [`redirectUrl`](#body-redirect-url) parameter.\n ",
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"refreshToken": {
"type": "string",
"pattern": "^[A-Za-z0-9-_]+(?:\\.[A-Za-z0-9-_]+)+$",
"description": "Refresh token to set in cookies."
},
"idToken": {
"type": "string",
"pattern": "^[A-Za-z0-9-_]+\\.[A-Za-z0-9-_]+\\.[A-Za-z0-9-_]+$",
"description": "JWT ID token for the user."
},
"checksum": {
"type": "string",
"description": "Mandatory checksum for the tokens."
},
"redirectUrl": {
"type": "string",
"format": "uri",
"description": "If provided, redirects to this URL after setting cookies. The URL must be within the Forestreet domain."
}
},
"required": ["refreshToken", "idToken", "checksum"]
}
}
}
},
"responses": {
"204": {
"description": "Session validated, and cookies set successfully; no `redirectUrl` provided.",
"headers": {
"Set-Cookie": {
"schema": {
"type": "string",
"description": "Authentication cookies set in the response headers."
},
"required": true,
"description": "Authentication cookies set in the response headers."
}
}
},
"302": {
"description": "Session validated, and cookies set successfully; redirecting user to `redirectUrl`.",
"headers": {
"Set-Cookie": {
"schema": {
"type": "string",
"description": "Authentication cookies set in the response headers."
},
"required": true,
"description": "Authentication cookies set in the response headers."
},
"Location": {
"schema": {
"type": "string",
"format": "uri",
"description": "The URL to redirect to after setting cookies."
},
"required": true,
"description": "The URL to redirect to after setting cookies."
}
}
},
"400": {
"description": "Bad Request - Invalid input",
"content": {
"application/json": {
"examples": {
"INVALID_INPUT": {
"value": {
"success": false,
"errorCode": "INVALID_INPUT",
"message": "Bad Request - Invalid input"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"401": {
"description": "Unauthorized - Invalid credentials, token or cookies",
"content": {
"application/json": {
"examples": {
"UNAUTHORISED": {
"value": {
"success": false,
"errorCode": "UNAUTHORISED",
"message": "Unauthorized - Invalid credentials, token or cookies"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
}
}
}
},
"/v2/teams": {
"get": {
"tags": ["Teams"],
"summary": "Get current user's teams",
"description": "Fetch the teams associated with the current user",
"parameters": [
{
"schema": {
"type": "integer",
"minimum": 0,
"exclusiveMinimum": true,
"default": 1,
"description": "Page number to retrieve, starting from 1."
},
"required": false,
"description": "Page number to retrieve, starting from 1.",
"name": "page",
"in": "query"
},
{
"schema": {
"type": "integer",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 100,
"default": 50,
"description": "Number of markets per page."
},
"required": false,
"description": "Number of markets per page.",
"name": "pageSize",
"in": "query"
}
],
"responses": {
"200": {
"description": "Get current user's teams response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"metadata": {
"type": "object",
"properties": {
"pagination": {
"type": "object",
"properties": {
"totalItems": {
"type": "number",
"description": "Total number of items for the returned dataset after filtering."
},
"totalPages": {
"type": "number",
"description": "Total number of pages for the returned dataset after filtering."
},
"currentPage": {
"type": "number",
"description": "Current page number."
},
"pageSize": {
"type": "number",
"description": "Number of items per page."
},
"unfilteredTotalItems": {
"type": "number",
"description": "Total number of items for the original dataset before filtering."
},
"unfilteredTotalPages": {
"type": "number",
"description": "Total number of pages for the original dataset before filtering."
}
},
"required": ["totalItems", "totalPages", "currentPage", "pageSize"],
"description": "Schema for pagination metadata, including total items, total pages, current page, and page size.",
"example": {
"totalItems": 123,
"totalPages": 13,
"currentPage": 1,
"pageSize": 10,
"unfilteredTotalItems": 196,
"unfilteredTotalPages": 20
}
}
},
"required": ["pagination"]
},
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "Unique identifier of the team."
},
"name": {
"type": "string",
"nullable": true,
"description": "Name of the team."
},
"domain": {
"type": "string",
"nullable": true,
"description": "Domain of the team."
},
"adminId": {
"type": "string",
"format": "uuid",
"description": "Admin ID of the team."
},
"filePath": {
"type": "string",
"nullable": true,
"description": "File path for the team."
},
"explorerPermissions": {
"type": "object",
"properties": {
"table": {
"type": "boolean"
},
"bubble": {
"type": "boolean"
},
"events": {
"type": "boolean"
},
"feature-fit": {
"type": "boolean"
}
},
"description": "Permission settings for explorer features."
},
"featurePermissions": {
"type": "object",
"properties": {
"notes": {
"type": "boolean"
},
"rapidReview": {
"type": "boolean"
},
"createTopic": {
"type": "boolean"
},
"createStudy": {
"type": "boolean"
},
"insights": {
"type": "boolean"
},
"editStudy": {
"type": "boolean"
},
"viewStudyStatus": {
"type": "boolean"
},
"manageTeams": {
"type": "boolean"
},
"editFeatureArchitecture": {
"type": "boolean"
},
"viewFeatureArchitecture": {
"type": "boolean"
},
"phraseSearch": {
"type": "boolean"
}
},
"default": {},
"description": "Feature permissions for the team (boolean map)."
},
"accessExpired": {
"type": "number",
"description": "Access expiration status."
},
"maxUsers": {
"type": "number",
"description": "Maximum number of users allowed."
},
"isDemo": {
"type": "number",
"description": "Demo status of the team."
},
"isDefault": {
"type": "number",
"description": "Default state of the team."
},
"theme": {
"type": "string",
"nullable": true,
"description": "Theme settings for the team."
},
"teamQuotas": {
"type": "object",
"properties": {
"startDiscovery": {
"type": "integer",
"nullable": true,
"description": "Quota for starting discoveries. Null means unlimited."
},
"createSupplierDossier": {
"type": "integer",
"nullable": true,
"description": "Quota for creating supplier dossiers. Null means unlimited."
}
},
"required": ["startDiscovery", "createSupplierDossier"],
"description": "Quota information for a team."
}
},
"required": [
"id",
"name",
"domain",
"adminId",
"filePath",
"explorerPermissions",
"accessExpired",
"maxUsers",
"isDemo",
"theme",
"teamQuotas"
]
}
}
},
"required": ["metadata", "data"]
}
}
}
},
"401": {
"description": "Unauthorized - User not authenticated",
"content": {
"application/json": {
"examples": {
"UNAUTHORISED": {
"value": {
"success": false,
"errorCode": "UNAUTHORISED",
"message": "Unauthorized - User not authenticated"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"examples": {
"FORBIDDEN": {
"value": {
"success": false,
"errorCode": "FORBIDDEN",
"message": "Forbidden"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
}
}
},
"post": {
"tags": ["Teams"],
"summary": "Create a team",
"description": "\n Creates a new team with the provided details.\n\n If no team admin is specified, the user making the request will be set as the team admin by default.\n\n \n **Restricted Endpoint**: This endpoint is built for Forestreet administration purposes only. It is not intended for public use and should not be accessed by non-administrators.\n If you believe you need access to this endpoint for legitimate reasons, please contact Forestreet support.\n\n We do not provide external support for this endpoint unless permissions had been negotiated in your contract.\n \n ",
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"domain": {
"type": "string"
},
"maxUsersCount": {
"type": "integer",
"minimum": 0,
"exclusiveMinimum": true
},
"teamAdmin": {
"type": "string",
"format": "uuid",
"description": "Cognito user sub."
},
"theme": {
"type": "string",
"nullable": true
},
"explorerPermissions": {
"type": "object",
"properties": {
"table": {
"type": "boolean"
},
"bubble": {
"type": "boolean"
},
"events": {
"type": "boolean"
},
"feature-fit": {
"type": "boolean"
}
},
"description": "Permission settings for explorer features."
},
"featurePermissions": {
"type": "array",
"items": {
"type": "string",
"enum": [
"notes",
"rapidReview",
"createTopic",
"createStudy",
"insights",
"editStudy",
"viewStudyStatus",
"manageTeams",
"editFeatureArchitecture",
"viewFeatureArchitecture",
"phraseSearch"
]
}
},
"isDemo": {
"type": "boolean",
"nullable": true
},
"teamQuotas": {
"type": "object",
"properties": {
"startDiscovery": {
"type": "integer",
"nullable": true,
"description": "Quota for starting discoveries. Null means unlimited."
},
"createSupplierDossier": {
"type": "integer",
"nullable": true,
"description": "Quota for creating supplier dossiers. Null means unlimited."
}
},
"required": ["startDiscovery", "createSupplierDossier"],
"description": "Quota information for a team."
}
},
"required": [
"name",
"domain",
"maxUsersCount",
"explorerPermissions",
"featurePermissions",
"teamQuotas"
]
}
}
}
},
"responses": {
"200": {
"description": "Team created successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "Unique identifier of the team."
},
"name": {
"type": "string",
"nullable": true,
"description": "Name of the team."
},
"domain": {
"type": "string",
"nullable": true,
"description": "Domain of the team."
},
"adminId": {
"type": "string",
"format": "uuid",
"description": "Admin ID of the team."
},
"filePath": {
"type": "string",
"nullable": true,
"description": "File path for the team."
},
"explorerPermissions": {
"type": "object",
"properties": {
"table": {
"type": "boolean"
},
"bubble": {
"type": "boolean"
},
"events": {
"type": "boolean"
},
"feature-fit": {
"type": "boolean"
}
},
"description": "Permission settings for explorer features."
},
"featurePermissions": {
"type": "object",
"properties": {
"notes": {
"type": "boolean"
},
"rapidReview": {
"type": "boolean"
},
"createTopic": {
"type": "boolean"
},
"createStudy": {
"type": "boolean"
},
"insights": {
"type": "boolean"
},
"editStudy": {
"type": "boolean"
},
"viewStudyStatus": {
"type": "boolean"
},
"manageTeams": {
"type": "boolean"
},
"editFeatureArchitecture": {
"type": "boolean"
},
"viewFeatureArchitecture": {
"type": "boolean"
},
"phraseSearch": {
"type": "boolean"
}
},
"default": {},
"description": "Feature permissions for the team (boolean map)."
},
"accessExpired": {
"type": "number",
"description": "Access expiration status."
},
"maxUsers": {
"type": "number",
"description": "Maximum number of users allowed."
},
"isDemo": {
"type": "number",
"description": "Demo status of the team."
},
"isDefault": {
"type": "number",
"description": "Default state of the team."
},
"theme": {
"type": "string",
"nullable": true,
"description": "Theme settings for the team."
},
"teamQuotas": {
"type": "object",
"properties": {
"startDiscovery": {
"type": "integer",
"nullable": true,
"description": "Quota for starting discoveries. Null means unlimited."
},
"createSupplierDossier": {
"type": "integer",
"nullable": true,
"description": "Quota for creating supplier dossiers. Null means unlimited."
}
},
"required": ["startDiscovery", "createSupplierDossier"],
"description": "Quota information for a team."
}
},
"required": [
"id",
"name",
"domain",
"adminId",
"filePath",
"explorerPermissions",
"accessExpired",
"maxUsers",
"isDemo",
"theme",
"teamQuotas"
]
}
}
}
},
"400": {
"description": "Bad Request - Invalid input",
"content": {
"application/json": {
"examples": {
"INVALID_INPUT": {
"value": {
"success": false,
"errorCode": "INVALID_INPUT",
"message": "Bad Request - Invalid input"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"403": {
"description": "Forbidden - User does not have permission to create a team",
"content": {
"application/json": {
"examples": {
"FORBIDDEN": {
"value": {
"success": false,
"errorCode": "FORBIDDEN",
"message": "Forbidden - User does not have permission to create a team"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
}
}
}
},
"/v2/teams/{teamId}": {
"patch": {
"tags": ["Teams"],
"summary": "Edit a team",
"description": "\n Edits a team with the provided details.\n\n \n **Restricted Endpoint**: This endpoint is built for Forestreet administration purposes only. It is not intended for public use and should not be accessed by non-administrators.\n If you believe you need access to this endpoint for legitimate reasons, please contact Forestreet support.\n\n We do not provide external support for this endpoint unless permissions had been negotiated in your contract.\n \n ",
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"domain": {
"type": "string"
},
"teamAdmin": {
"type": "string",
"format": "uuid",
"description": "Cognito user sub."
},
"theme": {
"type": "string",
"nullable": true
}
}
}
}
}
},
"responses": {
"204": {
"description": "No content",
"content": {
"application/json": {
"schema": {}
}
}
},
"400": {
"description": "Bad Request - Invalid input",
"content": {
"application/json": {
"examples": {
"INVALID_INPUT": {
"value": {
"success": false,
"errorCode": "INVALID_INPUT",
"message": "Bad Request - Invalid input"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"403": {
"description": "Forbidden - User does not have permission to edit a team",
"content": {
"application/json": {
"examples": {
"FORBIDDEN": {
"value": {
"success": false,
"errorCode": "FORBIDDEN",
"message": "Forbidden - User does not have permission to edit a team"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
}
}
},
"delete": {
"tags": ["Teams"],
"summary": "Delete a team",
"description": "\n Delete the specified team.\n\n \n **Restricted Endpoint**: This endpoint is built for Forestreet administration purposes only. It is not intended for public use and should not be accessed by non-administrators.\n If you believe you need access to this endpoint for legitimate reasons, please contact Forestreet support.\n\n We do not provide external support for this endpoint unless permissions had been negotiated in your contract.\n \n ",
"parameters": [
{
"schema": {
"type": "integer",
"minimum": 0,
"exclusiveMinimum": true,
"description": "ID of the team to delete."
},
"required": true,
"description": "ID of the team to delete.",
"name": "teamId",
"in": "path"
}
],
"responses": {
"204": {
"description": "Team deleted successfully",
"content": {
"application/json": {
"schema": {}
}
}
},
"401": {
"description": "Unauthorized - User not authenticated",
"content": {
"application/json": {
"examples": {
"UNAUTHORISED": {
"value": {
"success": false,
"errorCode": "UNAUTHORISED",
"message": "Unauthorized - User not authenticated"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"403": {
"description": "Forbidden - Requires forestreet admin authentication",
"content": {
"application/json": {
"examples": {
"FORBIDDEN": {
"value": {
"success": false,
"errorCode": "FORBIDDEN",
"message": "Forbidden - Requires forestreet admin authentication"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"404": {
"description": "Team not found",
"content": {
"application/json": {
"examples": {
"NOT_FOUND": {
"value": {
"success": false,
"errorCode": "NOT_FOUND",
"message": "Team not found"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
}
}
},
"get": {
"tags": ["Teams"],
"summary": "Get a team by ID",
"description": "Fetch the details of a specific team by its ID.",
"parameters": [
{
"schema": {
"type": "integer",
"minimum": 0,
"exclusiveMinimum": true,
"description": "ID of the team whose collections are being retrieved."
},
"required": true,
"description": "ID of the team whose collections are being retrieved.",
"name": "teamId",
"in": "path"
}
],
"responses": {
"200": {
"description": "Get team response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "Unique identifier of the team."
},
"name": {
"type": "string",
"nullable": true,
"description": "Name of the team."
},
"domain": {
"type": "string",
"nullable": true,
"description": "Domain of the team."
},
"adminId": {
"type": "string",
"format": "uuid",
"description": "Admin ID of the team."
},
"filePath": {
"type": "string",
"nullable": true,
"description": "File path for the team."
},
"explorerPermissions": {
"type": "object",
"properties": {
"table": {
"type": "boolean"
},
"bubble": {
"type": "boolean"
},
"events": {
"type": "boolean"
},
"feature-fit": {
"type": "boolean"
}
},
"description": "Permission settings for explorer features."
},
"featurePermissions": {
"type": "object",
"properties": {
"notes": {
"type": "boolean"
},
"rapidReview": {
"type": "boolean"
},
"createTopic": {
"type": "boolean"
},
"createStudy": {
"type": "boolean"
},
"insights": {
"type": "boolean"
},
"editStudy": {
"type": "boolean"
},
"viewStudyStatus": {
"type": "boolean"
},
"manageTeams": {
"type": "boolean"
},
"editFeatureArchitecture": {
"type": "boolean"
},
"viewFeatureArchitecture": {
"type": "boolean"
},
"phraseSearch": {
"type": "boolean"
}
},
"default": {},
"description": "Feature permissions for the team (boolean map)."
},
"accessExpired": {
"type": "number",
"description": "Access expiration status."
},
"maxUsers": {
"type": "number",
"description": "Maximum number of users allowed."
},
"isDemo": {
"type": "number",
"description": "Demo status of the team."
},
"isDefault": {
"type": "number",
"description": "Default state of the team."
},
"theme": {
"type": "string",
"nullable": true,
"description": "Theme settings for the team."
},
"teamQuotas": {
"type": "object",
"properties": {
"startDiscovery": {
"type": "integer",
"nullable": true,
"description": "Quota for starting discoveries. Null means unlimited."
},
"createSupplierDossier": {
"type": "integer",
"nullable": true,
"description": "Quota for creating supplier dossiers. Null means unlimited."
}
},
"required": ["startDiscovery", "createSupplierDossier"],
"description": "Quota information for a team."
}
},
"required": [
"id",
"name",
"domain",
"adminId",
"filePath",
"explorerPermissions",
"accessExpired",
"maxUsers",
"isDemo",
"theme",
"teamQuotas"
]
}
}
}
},
"401": {
"description": "Unauthorized - User not authenticated",
"content": {
"application/json": {
"examples": {
"UNAUTHORISED": {
"value": {
"success": false,
"errorCode": "UNAUTHORISED",
"message": "Unauthorized - User not authenticated"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"403": {
"description": "Forbidden - You do not have access to this team",
"content": {
"application/json": {
"examples": {
"FORBIDDEN": {
"value": {
"success": false,
"errorCode": "FORBIDDEN",
"message": "Forbidden - You do not have access to this team"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"404": {
"description": "Team not found",
"content": {
"application/json": {
"examples": {
"NOT_FOUND": {
"value": {
"success": false,
"errorCode": "NOT_FOUND",
"message": "Team not found"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
}
}
}
},
"/v2/teams/{teamId}/users": {
"get": {
"tags": ["Teams"],
"summary": "Get team users, advanced",
"description": "Fetch the users associated with a specific team",
"parameters": [
{
"schema": {
"type": "integer",
"minimum": 0,
"exclusiveMinimum": true,
"description": "ID of the team whose collections are being retrieved."
},
"required": true,
"description": "ID of the team whose collections are being retrieved.",
"name": "teamId",
"in": "path"
},
{
"schema": {
"type": "number",
"minimum": 1,
"maximum": 100,
"default": 10,
"description": "Number of items per page, default is 10, minimum is 1, maximum is 100."
},
"required": false,
"description": "Number of items per page, default is 10, minimum is 1, maximum is 100.",
"name": "pageSize",
"in": "query"
},
{
"schema": {
"type": "number",
"minimum": 1,
"default": 1,
"description": "Current page number, default is 1."
},
"required": false,
"description": "Current page number, default is 1.",
"name": "page",
"in": "query"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"nullable": true,
"properties": {
"filters": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Filter users by ID."
},
"firstName": {
"type": "string",
"description": "Filter users by first name."
},
"lastName": {
"type": "string",
"description": "Filter users by last name."
},
"fullName": {
"type": "string",
"description": "Filter users by full name."
},
"email": {
"type": "string",
"description": "Filter users by email."
}
},
"additionalProperties": false
},
"sortBy": {
"type": "array",
"items": {
"type": "object",
"properties": {
"field": {
"type": "string",
"enum": ["firstName", "lastName", "fullName", "email"],
"description": "Fields to sort team users by."
},
"order": {
"type": "string",
"enum": ["asc", "desc"],
"description": "Sort order according to the specified field."
}
},
"required": ["field", "order"],
"additionalProperties": false
},
"default": [
{
"field": "firstName",
"order": "asc"
}
],
"description": "Sorting criteria for the team users."
}
},
"additionalProperties": false,
"description": "Request body schema for getting team users, used for filtering and sorting users."
}
}
}
},
"responses": {
"200": {
"description": "Get team users response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"metadata": {
"type": "object",
"properties": {
"totalItems": {
"type": "number"
},
"maxUsers": {
"type": "number"
}
},
"required": ["totalItems", "maxUsers"]
},
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"firstName": {
"type": "string"
},
"lastName": {
"type": "string"
},
"fullName": {
"type": "string"
},
"email": {
"type": "string"
},
"role": {
"type": "string",
"enum": ["admin", "member"]
},
"createdAt": {
"type": "string",
"format": "date-time"
}
},
"required": ["id"]
}
}
},
"required": ["metadata", "data"]
}
}
}
},
"401": {
"description": "Unauthorized - User not authenticated",
"content": {
"application/json": {
"examples": {
"UNAUTHORISED": {
"value": {
"success": false,
"errorCode": "UNAUTHORISED",
"message": "Unauthorized - User not authenticated"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"403": {
"description": "Forbidden - You do not have access to this team",
"content": {
"application/json": {
"examples": {
"FORBIDDEN": {
"value": {
"success": false,
"errorCode": "FORBIDDEN",
"message": "Forbidden - You do not have access to this team"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"404": {
"description": "Team not found",
"content": {
"application/json": {
"examples": {
"NOT_FOUND": {
"value": {
"success": false,
"errorCode": "NOT_FOUND",
"message": "Team not found"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
}
}
},
"post": {
"tags": ["Teams"],
"summary": "Get team users",
"description": "Fetch the users associated with a specific team",
"parameters": [
{
"schema": {
"type": "integer",
"minimum": 0,
"exclusiveMinimum": true,
"description": "ID of the team whose collections are being retrieved."
},
"required": true,
"description": "ID of the team whose collections are being retrieved.",
"name": "teamId",
"in": "path"
},
{
"schema": {
"type": "number",
"minimum": 1,
"maximum": 100,
"default": 10,
"description": "Number of items per page, default is 10, minimum is 1, maximum is 100."
},
"required": false,
"description": "Number of items per page, default is 10, minimum is 1, maximum is 100.",
"name": "pageSize",
"in": "query"
},
{
"schema": {
"type": "number",
"minimum": 1,
"default": 1,
"description": "Current page number, default is 1."
},
"required": false,
"description": "Current page number, default is 1.",
"name": "page",
"in": "query"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"nullable": true,
"properties": {
"filters": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Filter users by ID."
},
"firstName": {
"type": "string",
"description": "Filter users by first name."
},
"lastName": {
"type": "string",
"description": "Filter users by last name."
},
"fullName": {
"type": "string",
"description": "Filter users by full name."
},
"email": {
"type": "string",
"description": "Filter users by email."
}
},
"additionalProperties": false
},
"sortBy": {
"type": "array",
"items": {
"type": "object",
"properties": {
"field": {
"type": "string",
"enum": ["firstName", "lastName", "fullName", "email"],
"description": "Fields to sort team users by."
},
"order": {
"type": "string",
"enum": ["asc", "desc"],
"description": "Sort order according to the specified field."
}
},
"required": ["field", "order"],
"additionalProperties": false
},
"default": [
{
"field": "firstName",
"order": "asc"
}
],
"description": "Sorting criteria for the team users."
}
},
"additionalProperties": false,
"description": "Request body schema for getting team users, used for filtering and sorting users."
}
}
}
},
"responses": {
"200": {
"description": "Get team users response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"metadata": {
"type": "object",
"properties": {
"totalItems": {
"type": "number"
},
"maxUsers": {
"type": "number"
}
},
"required": ["totalItems", "maxUsers"]
},
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"firstName": {
"type": "string"
},
"lastName": {
"type": "string"
},
"fullName": {
"type": "string"
},
"email": {
"type": "string"
},
"role": {
"type": "string",
"enum": ["admin", "member"]
},
"createdAt": {
"type": "string",
"format": "date-time"
}
},
"required": ["id"]
}
}
},
"required": ["metadata", "data"]
}
}
}
},
"401": {
"description": "Unauthorized - User not authenticated",
"content": {
"application/json": {
"examples": {
"UNAUTHORISED": {
"value": {
"success": false,
"errorCode": "UNAUTHORISED",
"message": "Unauthorized - User not authenticated"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"403": {
"description": "Forbidden - You do not have access to this team",
"content": {
"application/json": {
"examples": {
"FORBIDDEN": {
"value": {
"success": false,
"errorCode": "FORBIDDEN",
"message": "Forbidden - You do not have access to this team"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"404": {
"description": "Team not found",
"content": {
"application/json": {
"examples": {
"NOT_FOUND": {
"value": {
"success": false,
"errorCode": "NOT_FOUND",
"message": "Team not found"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
}
}
}
},
"/v2/teams/{teamId}/collections": {
"get": {
"tags": ["Teams"],
"summary": "Get team collections",
"description": "Fetch the collections associated with a specific team",
"parameters": [
{
"schema": {
"type": "integer",
"minimum": 0,
"exclusiveMinimum": true,
"description": "ID of the team whose collections are being retrieved."
},
"required": true,
"description": "ID of the team whose collections are being retrieved.",
"name": "teamId",
"in": "path"
},
{
"schema": {
"type": "integer",
"minimum": 0,
"exclusiveMinimum": true,
"default": 1,
"description": "Page number to retrieve, starting from 1."
},
"required": false,
"description": "Page number to retrieve, starting from 1.",
"name": "page",
"in": "query"
},
{
"schema": {
"type": "integer",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 100,
"default": 50,
"description": "Number of markets per page."
},
"required": false,
"description": "Number of markets per page.",
"name": "pageSize",
"in": "query"
}
],
"responses": {
"200": {
"description": "Get team collections response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"metadata": {
"type": "object",
"properties": {
"pagination": {
"type": "object",
"properties": {
"totalItems": {
"type": "number",
"description": "Total number of items for the returned dataset after filtering."
},
"totalPages": {
"type": "number",
"description": "Total number of pages for the returned dataset after filtering."
},
"currentPage": {
"type": "number",
"description": "Current page number."
},
"pageSize": {
"type": "number",
"description": "Number of items per page."
},
"unfilteredTotalItems": {
"type": "number",
"description": "Total number of items for the original dataset before filtering."
},
"unfilteredTotalPages": {
"type": "number",
"description": "Total number of pages for the original dataset before filtering."
}
},
"required": ["totalItems", "totalPages", "currentPage", "pageSize"],
"description": "Schema for pagination metadata, including total items, total pages, current page, and page size.",
"example": {
"totalItems": 123,
"totalPages": 13,
"currentPage": 1,
"pageSize": 10,
"unfilteredTotalItems": 196,
"unfilteredTotalPages": 20
}
}
},
"required": ["pagination"]
},
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "Unique identifier of the collection."
},
"name": {
"type": "string",
"description": "Name of the collection."
},
"description": {
"type": "string",
"description": "Optional description of the collection."
},
"createdDate": {
"type": "string",
"format": "date-time",
"description": "Date string representing when the collection was created."
},
"isUserCreated": {
"type": "number",
"description": "Indicates if the collection was created by a user (1 for true, 0 for false)."
},
"isDefault": {
"type": "number",
"description": "Indicates if the collection is the team's default collection (1 for true, 0 for false)."
},
"isPrivate": {
"type": "number",
"description": "Indicates if the collection is private (1 for true, 0 for false)."
}
},
"required": ["id", "name", "createdDate"]
}
}
},
"required": ["metadata", "data"]
}
}
}
},
"401": {
"description": "Unauthorized - User not authenticated",
"content": {
"application/json": {
"examples": {
"UNAUTHORISED": {
"value": {
"success": false,
"errorCode": "UNAUTHORISED",
"message": "Unauthorized - User not authenticated"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"403": {
"description": "Forbidden - You do not have access to this team",
"content": {
"application/json": {
"examples": {
"FORBIDDEN": {
"value": {
"success": false,
"errorCode": "FORBIDDEN",
"message": "Forbidden - You do not have access to this team"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
}
}
},
"post": {
"tags": ["Teams"],
"summary": "Create a collection",
"description": "\n Create a collection within a specific team.\n\n The authenticated user must have access to the team.\n ",
"parameters": [
{
"schema": {
"type": "integer",
"minimum": 0,
"exclusiveMinimum": true,
"description": "ID of the team whose collections are being retrieved."
},
"required": true,
"description": "ID of the team whose collections are being retrieved.",
"name": "teamId",
"in": "path"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"minLength": 1,
"description": "Name of the new collection."
},
"description": {
"type": "string",
"description": "Optional description of the new collection."
},
"isPrivate": {
"type": "boolean",
"description": "Whether the collection is private. Defaults to true."
},
"isUserCreated": {
"type": "boolean",
"description": "Indicates whether the collection was created by a user."
},
"isDefault": {
"type": "boolean",
"description": "Indicates whether the collection is set as the default."
}
},
"required": ["name"],
"description": "Request body schema for creating a new collection."
}
}
}
},
"responses": {
"200": {
"description": "Collection created successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "Unique identifier for the collection."
},
"name": {
"type": "string",
"description": "The name of the collection."
},
"description": {
"type": "string",
"description": "Optional description providing additional details about the collection."
},
"createdDate": {
"type": "string",
"description": "The date when the collection was created."
},
"isUserCreated": {
"type": "number",
"description": "Indicates whether the collection was created by a user."
},
"isDefault": {
"type": "number",
"description": "Indicates whether the collection is set as the default."
},
"isPrivate": {
"type": "number",
"description": "Indicates whether the collection is private."
}
},
"required": ["id", "name", "createdDate"]
}
}
}
},
"400": {
"description": "Bad Request - Invalid input",
"content": {
"application/json": {
"examples": {
"INVALID_INPUT": {
"value": {
"success": false,
"errorCode": "INVALID_INPUT",
"message": "Bad Request - Invalid input"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"401": {
"description": "Unauthorized - User not authenticated",
"content": {
"application/json": {
"examples": {
"UNAUTHORISED": {
"value": {
"success": false,
"errorCode": "UNAUTHORISED",
"message": "Unauthorized - User not authenticated"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"403": {
"description": "Forbidden - You do not have access to this team",
"content": {
"application/json": {
"examples": {
"FORBIDDEN": {
"value": {
"success": false,
"errorCode": "FORBIDDEN",
"message": "Forbidden - You do not have access to this team"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"examples": {
"INTERNAL_SERVER_ERROR": {
"value": {
"success": false,
"errorCode": "INTERNAL_SERVER_ERROR",
"message": "Internal Server Error"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
}
}
}
},
"/v2/teams/{teamId}/endpoints": {
"get": {
"tags": ["Teams"],
"summary": "Get team export endpoints",
"description": "Fetch the Export Via API endpoints associated with a specific team",
"parameters": [
{
"schema": {
"type": "number",
"nullable": true,
"minimum": 0
},
"required": false,
"name": "teamId",
"in": "path"
},
{
"schema": {
"type": "number",
"minimum": 1,
"maximum": 100,
"default": 10,
"description": "Number of items per page, default is 10, minimum is 1, maximum is 100."
},
"required": false,
"description": "Number of items per page, default is 10, minimum is 1, maximum is 100.",
"name": "pageSize",
"in": "query"
},
{
"schema": {
"type": "number",
"minimum": 1,
"default": 1,
"description": "Current page number, default is 1."
},
"required": false,
"description": "Current page number, default is 1.",
"name": "page",
"in": "query"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"filters": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Filter endpoints by name."
},
"description": {
"type": "string",
"description": "Filter endpoints by description."
},
"url": {
"type": "string",
"description": "Filter endpoints by URL."
},
"version": {
"type": "integer",
"minimum": 1,
"description": "Filter endpoints by version."
}
},
"additionalProperties": false
},
"sortBy": {
"type": "array",
"items": {
"type": "object",
"properties": {
"field": {
"type": "string",
"enum": ["name", "url"],
"description": "Fields to sort agents by."
},
"order": {
"type": "string",
"enum": ["asc", "desc"],
"description": "Sort order according to the specified field."
}
},
"required": ["field", "order"],
"additionalProperties": false
},
"default": [
{
"field": "name",
"order": "asc"
}
],
"description": "Sorting criteria for the endpoints."
}
},
"additionalProperties": false,
"description": "Request body schema for getting team endpoints, used for filtering and sorting endpoints."
}
}
}
},
"responses": {
"200": {
"description": "Get team endpoints response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"metadata": {
"type": "object",
"properties": {
"teamId": {
"type": "number",
"nullable": true,
"minimum": 0,
"description": "ID of the team whose endpoints are being retrieved."
},
"filters": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Filter endpoints by name."
},
"description": {
"type": "string",
"description": "Filter endpoints by description."
},
"url": {
"type": "string",
"description": "Filter endpoints by URL."
},
"version": {
"type": "integer",
"minimum": 1,
"description": "Filter endpoints by version."
}
},
"additionalProperties": false
},
"sortBy": {
"type": "array",
"items": {
"type": "object",
"properties": {
"field": {
"type": "string",
"enum": ["name", "url"],
"description": "Fields to sort agents by."
},
"order": {
"type": "string",
"enum": ["asc", "desc"],
"description": "Sort order according to the specified field."
}
},
"required": ["field", "order"],
"additionalProperties": false
},
"description": "Sorting criteria for the endpoints."
},
"pagination": {
"type": "object",
"properties": {
"totalItems": {
"type": "number",
"description": "Total number of items for the returned dataset after filtering."
},
"totalPages": {
"type": "number",
"description": "Total number of pages for the returned dataset after filtering."
},
"currentPage": {
"type": "number",
"description": "Current page number."
},
"pageSize": {
"type": "number",
"description": "Number of items per page."
},
"unfilteredTotalItems": {
"type": "number",
"description": "Total number of items for the original dataset before filtering."
},
"unfilteredTotalPages": {
"type": "number",
"description": "Total number of pages for the original dataset before filtering."
}
},
"required": ["totalItems", "totalPages", "currentPage", "pageSize"],
"description": "Schema for pagination metadata, including total items, total pages, current page, and page size.",
"example": {
"totalItems": 123,
"totalPages": 13,
"currentPage": 1,
"pageSize": 10,
"unfilteredTotalItems": 196,
"unfilteredTotalPages": 20
}
}
},
"required": ["teamId", "pagination"]
},
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Name of the endpoint, used to identify it in the system."
},
"description": {
"type": "string",
"description": "Description of the endpoint, providing details about its purpose and usage."
},
"url": {
"type": "string",
"format": "uri",
"description": "URL of the endpoint to be called."
},
"headers": {
"type": "object",
"nullable": true,
"additionalProperties": {
"type": "string"
},
"description": "Headers to be included in the request to the endpoint."
},
"version": {
"type": "integer",
"minimum": 1,
"description": "Version of the endpoint, stating compatibility of the endpoint with the version of Export Via API mechanism."
}
},
"required": ["name", "description", "url", "headers", "version"]
},
"description": "Array of endpoints associated with the team."
}
},
"required": ["metadata", "data"]
}
}
}
},
"401": {
"description": "Unauthorized - User not authenticated",
"content": {
"application/json": {
"examples": {
"UNAUTHORISED": {
"value": {
"success": false,
"errorCode": "UNAUTHORISED",
"message": "Unauthorized - User not authenticated"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"403": {
"description": "Forbidden - You do not have access to this team",
"content": {
"application/json": {
"examples": {
"FORBIDDEN": {
"value": {
"success": false,
"errorCode": "FORBIDDEN",
"message": "Forbidden - You do not have access to this team"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
}
}
},
"post": {
"tags": ["Teams"],
"summary": "Get team export endpoints, advanced",
"description": "Fetch the Export Via API endpoints associated with a specific team",
"parameters": [
{
"schema": {
"type": "number",
"nullable": true,
"minimum": 0
},
"required": false,
"name": "teamId",
"in": "path"
},
{
"schema": {
"type": "number",
"minimum": 1,
"maximum": 100,
"default": 10,
"description": "Number of items per page, default is 10, minimum is 1, maximum is 100."
},
"required": false,
"description": "Number of items per page, default is 10, minimum is 1, maximum is 100.",
"name": "pageSize",
"in": "query"
},
{
"schema": {
"type": "number",
"minimum": 1,
"default": 1,
"description": "Current page number, default is 1."
},
"required": false,
"description": "Current page number, default is 1.",
"name": "page",
"in": "query"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"filters": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Filter endpoints by name."
},
"description": {
"type": "string",
"description": "Filter endpoints by description."
},
"url": {
"type": "string",
"description": "Filter endpoints by URL."
},
"version": {
"type": "integer",
"minimum": 1,
"description": "Filter endpoints by version."
}
},
"additionalProperties": false
},
"sortBy": {
"type": "array",
"items": {
"type": "object",
"properties": {
"field": {
"type": "string",
"enum": ["name", "url"],
"description": "Fields to sort agents by."
},
"order": {
"type": "string",
"enum": ["asc", "desc"],
"description": "Sort order according to the specified field."
}
},
"required": ["field", "order"],
"additionalProperties": false
},
"default": [
{
"field": "name",
"order": "asc"
}
],
"description": "Sorting criteria for the endpoints."
}
},
"additionalProperties": false,
"description": "Request body schema for getting team endpoints, used for filtering and sorting endpoints."
}
}
}
},
"responses": {
"200": {
"description": "Get team endpoints response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"metadata": {
"type": "object",
"properties": {
"teamId": {
"type": "number",
"nullable": true,
"minimum": 0,
"description": "ID of the team whose endpoints are being retrieved."
},
"filters": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Filter endpoints by name."
},
"description": {
"type": "string",
"description": "Filter endpoints by description."
},
"url": {
"type": "string",
"description": "Filter endpoints by URL."
},
"version": {
"type": "integer",
"minimum": 1,
"description": "Filter endpoints by version."
}
},
"additionalProperties": false
},
"sortBy": {
"type": "array",
"items": {
"type": "object",
"properties": {
"field": {
"type": "string",
"enum": ["name", "url"],
"description": "Fields to sort agents by."
},
"order": {
"type": "string",
"enum": ["asc", "desc"],
"description": "Sort order according to the specified field."
}
},
"required": ["field", "order"],
"additionalProperties": false
},
"description": "Sorting criteria for the endpoints."
},
"pagination": {
"type": "object",
"properties": {
"totalItems": {
"type": "number",
"description": "Total number of items for the returned dataset after filtering."
},
"totalPages": {
"type": "number",
"description": "Total number of pages for the returned dataset after filtering."
},
"currentPage": {
"type": "number",
"description": "Current page number."
},
"pageSize": {
"type": "number",
"description": "Number of items per page."
},
"unfilteredTotalItems": {
"type": "number",
"description": "Total number of items for the original dataset before filtering."
},
"unfilteredTotalPages": {
"type": "number",
"description": "Total number of pages for the original dataset before filtering."
}
},
"required": ["totalItems", "totalPages", "currentPage", "pageSize"],
"description": "Schema for pagination metadata, including total items, total pages, current page, and page size.",
"example": {
"totalItems": 123,
"totalPages": 13,
"currentPage": 1,
"pageSize": 10,
"unfilteredTotalItems": 196,
"unfilteredTotalPages": 20
}
}
},
"required": ["teamId", "pagination"]
},
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Name of the endpoint, used to identify it in the system."
},
"description": {
"type": "string",
"description": "Description of the endpoint, providing details about its purpose and usage."
},
"url": {
"type": "string",
"format": "uri",
"description": "URL of the endpoint to be called."
},
"headers": {
"type": "object",
"nullable": true,
"additionalProperties": {
"type": "string"
},
"description": "Headers to be included in the request to the endpoint."
},
"version": {
"type": "integer",
"minimum": 1,
"description": "Version of the endpoint, stating compatibility of the endpoint with the version of Export Via API mechanism."
}
},
"required": ["name", "description", "url", "headers", "version"]
},
"description": "Array of endpoints associated with the team."
}
},
"required": ["metadata", "data"]
}
}
}
},
"401": {
"description": "Unauthorized - User not authenticated",
"content": {
"application/json": {
"examples": {
"UNAUTHORISED": {
"value": {
"success": false,
"errorCode": "UNAUTHORISED",
"message": "Unauthorized - User not authenticated"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"403": {
"description": "Forbidden - You do not have access to this team",
"content": {
"application/json": {
"examples": {
"FORBIDDEN": {
"value": {
"success": false,
"errorCode": "FORBIDDEN",
"message": "Forbidden - You do not have access to this team"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
}
}
}
},
"/v2/teams/{teamId}/endpoint/{endpointName}": {
"put": {
"tags": ["Teams"],
"summary": "Register export endpoint for a team",
"description": "\n Register a new Export Via API endpoint for a team.\n ",
"parameters": [
{
"schema": {
"type": "number",
"nullable": true,
"minimum": 0
},
"required": false,
"name": "teamId",
"in": "path"
},
{
"schema": {
"type": "string",
"maxLength": 255
},
"required": true,
"name": "endpointName",
"in": "path"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"url": {
"type": "string",
"minLength": 4,
"maxLength": 1024
},
"description": {
"type": "string",
"nullable": true,
"maxLength": 1024
},
"headers": {
"type": "object",
"nullable": true,
"additionalProperties": {
"type": "string"
}
},
"version": {
"type": "integer",
"minimum": 1,
"description": "Compatible version Export Via API mechanism."
}
},
"additionalProperties": false
}
}
}
},
"responses": {
"200": {
"description": "Successful registration of endpoint.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"metadata": {
"type": "object",
"properties": {
"endpoint": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Name of the endpoint, used to identify it in the system."
},
"description": {
"type": "string",
"description": "Description of the endpoint, providing details about its purpose and usage."
},
"url": {
"type": "string",
"format": "uri",
"description": "URL of the endpoint to be called."
},
"headers": {
"type": "object",
"nullable": true,
"additionalProperties": {
"type": "string"
},
"description": "Headers to be included in the request to the endpoint."
},
"version": {
"type": "integer",
"minimum": 1,
"description": "Version of the endpoint, stating compatibility of the endpoint with the version of Export Via API mechanism."
}
},
"required": ["name", "description", "url", "headers", "version"]
}
},
"required": ["endpoint"]
}
},
"required": ["metadata"]
}
}
}
},
"400": {
"description": "Validation of path parameters failed.",
"content": {
"application/json": {
"examples": {
"INVALID_INPUT": {
"value": {
"success": false,
"errorCode": "INVALID_INPUT",
"message": "Validation of path parameters failed."
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"403": {
"description": "Forbidden - User does not have access to the team",
"content": {
"application/json": {
"examples": {
"FORBIDDEN": {
"value": {
"success": false,
"errorCode": "FORBIDDEN",
"message": "Forbidden - User does not have access to the team"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"409": {
"description": "Conflict - Endpoint already exists",
"content": {
"application/json": {
"examples": {
"CONFLICT": {
"value": {
"success": false,
"errorCode": "CONFLICT",
"message": "Conflict - Endpoint already exists"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
}
}
},
"patch": {
"tags": ["Teams"],
"summary": "Update export endpoint for a team",
"description": "\n Update an existing Export Via API endpoint for a team.\n ",
"parameters": [
{
"schema": {
"type": "number",
"nullable": true,
"minimum": 0
},
"required": false,
"name": "teamId",
"in": "path"
},
{
"schema": {
"type": "string",
"maxLength": 255
},
"required": true,
"name": "endpointName",
"in": "path"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"url": {
"type": "string",
"minLength": 4,
"maxLength": 1024
},
"description": {
"type": "string",
"nullable": true,
"maxLength": 1024
},
"headers": {
"type": "object",
"nullable": true,
"additionalProperties": {
"type": "string"
}
},
"version": {
"type": "integer",
"minimum": 1,
"description": "Compatible version Export Via API mechanism."
}
},
"additionalProperties": false
}
}
}
},
"responses": {
"200": {
"description": "Successful update of endpoint.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"metadata": {
"type": "object",
"properties": {
"endpoint": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Name of the endpoint, used to identify it in the system."
},
"description": {
"type": "string",
"description": "Description of the endpoint, providing details about its purpose and usage."
},
"url": {
"type": "string",
"format": "uri",
"description": "URL of the endpoint to be called."
},
"headers": {
"type": "object",
"nullable": true,
"additionalProperties": {
"type": "string"
},
"description": "Headers to be included in the request to the endpoint."
},
"version": {
"type": "integer",
"minimum": 1,
"description": "Version of the endpoint, stating compatibility of the endpoint with the version of Export Via API mechanism."
}
},
"required": ["name", "description", "url", "headers", "version"]
}
},
"required": ["endpoint"]
},
"updated": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of fields that were updated in the endpoint metadata."
}
},
"required": ["metadata", "updated"]
}
}
}
},
"400": {
"description": "Validation of path parameters failed.",
"content": {
"application/json": {
"examples": {
"INVALID_INPUT": {
"value": {
"success": false,
"errorCode": "INVALID_INPUT",
"message": "Validation of path parameters failed."
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"403": {
"description": "Forbidden - User does not have access to the team",
"content": {
"application/json": {
"examples": {
"FORBIDDEN": {
"value": {
"success": false,
"errorCode": "FORBIDDEN",
"message": "Forbidden - User does not have access to the team"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"404": {
"description": "Endpoint not found - Cannot update non-existing endpoint",
"content": {
"application/json": {
"examples": {
"NOT_FOUND": {
"value": {
"success": false,
"errorCode": "NOT_FOUND",
"message": "Endpoint not found - Cannot update non-existing endpoint"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
}
}
},
"delete": {
"tags": ["Teams"],
"summary": "Delete export endpoint for a team",
"description": "\n Delete an existing Export Via API endpoint for a team.\n ",
"parameters": [
{
"schema": {
"type": "number",
"nullable": true,
"minimum": 0
},
"required": false,
"name": "teamId",
"in": "path"
},
{
"schema": {
"type": "string",
"maxLength": 255
},
"required": true,
"name": "endpointName",
"in": "path"
}
],
"responses": {
"204": {
"description": "Endpoint deleted successfully.",
"content": {
"application/json": {
"schema": {}
}
}
},
"400": {
"description": "Validation of path parameters failed.",
"content": {
"application/json": {
"examples": {
"INVALID_INPUT": {
"value": {
"success": false,
"errorCode": "INVALID_INPUT",
"message": "Validation of path parameters failed."
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"403": {
"description": "Forbidden - User does not have access to the team",
"content": {
"application/json": {
"examples": {
"FORBIDDEN": {
"value": {
"success": false,
"errorCode": "FORBIDDEN",
"message": "Forbidden - User does not have access to the team"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"404": {
"description": "Endpoint not found - Cannot delete non-existing endpoint",
"content": {
"application/json": {
"examples": {
"NOT_FOUND": {
"value": {
"success": false,
"errorCode": "NOT_FOUND",
"message": "Endpoint not found - Cannot delete non-existing endpoint"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
}
}
}
},
"/v2/users/me": {
"get": {
"tags": ["Users"],
"summary": "About me",
"description": "\n Get the current user's information and their access to teams and collections.\n\n This endpoint returns the user's authentication metadata, including their ID and email,\n as well as the IDs of teams and collections they have access to.\n ",
"responses": {
"200": {
"description": "Current user information",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"sub": {
"type": "string"
},
"authenticationMethod": {
"type": "string",
"enum": ["token", "apiKey", "specialToken"]
},
"email": {
"type": "string"
},
"firstName": {
"type": "string"
},
"lastName": {
"type": "string"
},
"identities": {
"type": "array",
"items": {
"type": "object",
"properties": {
"userId": {
"type": "string"
},
"providerName": {
"type": "string"
},
"providerType": {
"type": "string"
},
"issuer": {
"type": "string",
"nullable": true
},
"primary": {
"type": "boolean"
},
"dateCreated": {
"type": "number"
}
},
"required": ["userId", "providerName", "providerType", "issuer", "primary", "dateCreated"]
}
},
"userStatus": {
"type": "string",
"enum": [
"UNCONFIRMED",
"CONFIRMED",
"EXTERNAL_PROVIDER",
"RESET_REQUIRED",
"FORCE_CHANGE_PASSWORD"
]
},
"customAttributes": {
"type": "object",
"properties": {
"promoGroupName": {
"type": "string",
"nullable": true
},
"isNewUser": {
"type": "boolean"
},
"isTermsAgreed": {
"type": "boolean"
},
"theme": {
"type": "string"
},
"ailsaPreferences": {
"type": "object",
"properties": {
"activeWidgets": {
"type": "array",
"items": {
"type": "string"
}
},
"isWidgetsHidden": {
"type": "boolean"
},
"tableShownColumns": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": ["activeWidgets", "isWidgetsHidden", "tableShownColumns"]
},
"internalPermissions": {
"type": "array",
"items": {
"type": "string",
"enum": [
"user.admin",
"user.dev",
"api.platform",
"api.beroe",
"beroe.analyst",
"beroe.research-team"
],
"description": "Internal permissions are only set for Forestreet internal users, such as administrators or platform APIs that require special access to certain endpoints. Since our endpoints are public, we need these permissions to restrict access to certain functionalities."
},
"description": "An array of internal permissions, typically used to define what a user can do, or the permissions required to access certain endpoints."
}
},
"required": ["promoGroupName", "isNewUser", "isTermsAgreed", "theme"]
}
},
"required": ["sub", "authenticationMethod"]
}
}
}
},
"403": {
"description": "User not authenticated",
"content": {
"application/json": {
"examples": {
"FORBIDDEN": {
"value": {
"success": false,
"errorCode": "FORBIDDEN",
"message": "User not authenticated"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
}
}
}
},
"/v2/discovery/search-criteria": {
"post": {
"tags": ["Discovery"],
"summary": "Generate search criteria",
"description": "Convert natural language queries into structured search criteria for AI-powered company discovery.",
"requestBody": {
"content": {
"application/json": {
"examples": {
"ai-transcription": {
"summary": "AI Transcription Services",
"description": "Example for finding AI transcription services",
"value": {
"searchType": "keywordSearch",
"searchInput": "Find AI-powered transcription services that serve enterprise healthcare customers"
}
}
},
"schema": {
"type": "object",
"properties": {
"searchType": {
"type": "string",
"enum": ["keywordSearch", "domainSearch"],
"default": "keywordSearch",
"description": "Type of search to perform."
},
"searchInput": {
"type": "string",
"description": "Input for the search."
}
},
"required": ["searchInput"]
}
}
}
},
"responses": {
"200": {
"description": "Search criteria generated",
"content": {
"application/json": {
"examples": {
"ai-transcription-response": {
"summary": "AI Transcription Services Response",
"description": "Example response for AI transcription services search",
"value": {
"metadata": {},
"data": {
"userPrompt": "Find AI-powered transcription services that serve enterprise healthcare customers",
"marketName": "AI Healthcare Transcription Services",
"marketType": "service",
"marketRole": "serviceProvider",
"keywords": {
"features": ["AI transcription", "speech-to-text", "healthcare"],
"user": ["healthcare", "enterprise", "hospitals"],
"synonyms": ["transcription", "dictation", "voice-to-text"],
"irrelevant": ["manual transcription", "human transcription"]
},
"seedDomains": [],
"count": 50,
"locations": [
{
"country": "GB",
"address": ["123 Healthcare St", "Suite 100"],
"coordinates": [51.5074, -0.1278]
}
]
}
}
}
},
"schema": {
"type": "object",
"properties": {
"metadata": {
"type": "object",
"properties": {}
},
"data": {
"type": "object",
"properties": {
"userPrompt": {
"type": "string",
"description": "Prompt used to generate the search criteria."
},
"marketName": {
"type": "string",
"description": "Name of the market associated with the study."
},
"marketType": {
"type": "string",
"enum": ["service", "product"],
"description": "Type classification of the market, such as region or category."
},
"marketRole": {
"type": "string",
"enum": [
"manufacturer",
"distributor",
"serviceProvider",
"service provider",
"consultant",
"provider"
],
"description": "\nTry to limit the companies to ones that fit a specific role in the market. Possible values are:\n\n- `\"manufacturer\"` – physical product manufacturing, e.g. a car manufacturer \n- `\"distributor\"` – physical product distribution, e.g. a car dealership \n- `\"service provider\"` – contractor or provider of pre-defined services, e.g. a car repair shop \n- `\"consultant\"` – consultants or advisers not themselves participating in the market, but offer advice to those who do, e.g. a motor regulatory consultant\n\nThis is a hint to the discovery process and does not guarantee that all returned companies will fit this role. If insufficient companies are found, the search will be broadened to include other roles.\n\nIf not provided, the AI will attempt to infer the role based on the market name, and assumes `\"manufacturer\"` if the market is too broad.\n\n> 💡 It is recommended to write your intended role in the market name, which the AI will be able to infer from. Supplying a `marketRole` incompatible with the market name might degrade the output.\n"
},
"keywords": {
"type": "object",
"properties": {
"features": {
"type": "array",
"items": {
"type": "string"
},
"description": "Keywords related to the market's features."
},
"user": {
"type": "array",
"items": {
"type": "string"
},
"description": "Keywords related to user preferences or behavior."
},
"synonyms": {
"type": "array",
"items": {
"type": "string"
},
"description": "Alternative terms related to the market search."
},
"irrelevant": {
"type": "array",
"items": {
"type": "string"
},
"description": "Terms identified as irrelevant for the search criteria."
}
},
"required": ["features", "user", "synonyms", "irrelevant"],
"description": "Grouped keywords associated with the search criteria."
},
"seedDomains": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of company domains you already know (if any)."
},
"assertions": {
"nullable": true,
"description": "Assumptions made during the search criteria generation process."
},
"constraints": {
"nullable": true,
"description": "Constraints applied to the search criteria generation process."
},
"locations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"country": {
"type": "string",
"nullable": true
},
"address": {
"type": "array",
"nullable": true,
"items": {
"type": "string"
}
},
"coordinates": {
"type": "array",
"nullable": true,
"items": {
"type": "number"
},
"minItems": 2,
"maxItems": 2
}
},
"required": ["country"]
},
"description": "List of country relevant to the study."
}
},
"required": ["userPrompt", "marketName", "marketType", "marketRole", "keywords", "locations"]
}
},
"required": ["metadata", "data"]
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"examples": {
"INVALID_INPUT": {
"value": {
"success": false,
"errorCode": "INVALID_INPUT",
"message": "Bad Request"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"401": {
"description": "Unauthorized - User not authenticated",
"content": {
"application/json": {
"examples": {
"UNAUTHORISED": {
"value": {
"success": false,
"errorCode": "UNAUTHORISED",
"message": "Unauthorized - User not authenticated"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"examples": {
"FORBIDDEN": {
"value": {
"success": false,
"errorCode": "FORBIDDEN",
"message": "Forbidden"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"examples": {
"INTERNAL_SERVER_ERROR": {
"value": {
"success": false,
"errorCode": "INTERNAL_SERVER_ERROR",
"message": "Internal Server Error"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
}
}
}
},
"/v2/discovery/search-criteria/keywords": {
"post": {
"tags": ["Discovery"],
"summary": "Generate keywords for search",
"description": "Generate AI-suggested keywords to improve your search criteria.",
"requestBody": {
"content": {
"application/json": {
"examples": {
"ai-transcription": {
"summary": "AI Transcription Services",
"description": "Example for finding AI transcription services",
"value": {
"userPrompt": "Find AI-powered transcription services that serve enterprise healthcare customers",
"marketName": "AI Healthcare Transcription Services",
"marketType": "service",
"marketRole": "serviceProvider",
"keywords": {
"features": ["AI transcription", "speech-to-text", "healthcare"],
"user": ["healthcare", "enterprise", "hospitals"],
"synonyms": ["transcription", "dictation", "voice-to-text"],
"irrelevant": ["manual transcription", "human transcription"]
},
"seedDomains": [],
"count": 50,
"locations": [
{
"country": "GB",
"address": ["123 Healthcare St", "Suite 100"],
"coordinates": [51.5074, -0.1278]
}
]
}
}
},
"schema": {
"type": "object",
"properties": {
"searchCriteria": {
"type": "object",
"properties": {
"userPrompt": {
"type": "string",
"description": "Prompt used to generate the search criteria."
},
"marketName": {
"type": "string",
"description": "Name of the market associated with the study."
},
"marketType": {
"type": "string",
"enum": ["service", "product"],
"description": "Type classification of the market, such as region or category."
},
"marketRole": {
"type": "string",
"enum": [
"manufacturer",
"distributor",
"serviceProvider",
"service provider",
"consultant",
"provider"
],
"description": "\nTry to limit the companies to ones that fit a specific role in the market. Possible values are:\n\n- `\"manufacturer\"` – physical product manufacturing, e.g. a car manufacturer \n- `\"distributor\"` – physical product distribution, e.g. a car dealership \n- `\"service provider\"` – contractor or provider of pre-defined services, e.g. a car repair shop \n- `\"consultant\"` – consultants or advisers not themselves participating in the market, but offer advice to those who do, e.g. a motor regulatory consultant\n\nThis is a hint to the discovery process and does not guarantee that all returned companies will fit this role. If insufficient companies are found, the search will be broadened to include other roles.\n\nIf not provided, the AI will attempt to infer the role based on the market name, and assumes `\"manufacturer\"` if the market is too broad.\n\n> 💡 It is recommended to write your intended role in the market name, which the AI will be able to infer from. Supplying a `marketRole` incompatible with the market name might degrade the output.\n"
},
"keywords": {
"type": "object",
"properties": {
"features": {
"type": "array",
"items": {
"type": "string"
},
"description": "Keywords related to the market's features."
},
"user": {
"type": "array",
"items": {
"type": "string"
},
"description": "Keywords related to user preferences or behavior."
},
"synonyms": {
"type": "array",
"items": {
"type": "string"
},
"description": "Alternative terms related to the market search."
},
"irrelevant": {
"type": "array",
"items": {
"type": "string"
},
"description": "Terms identified as irrelevant for the search criteria."
}
},
"required": ["features", "user", "synonyms", "irrelevant"],
"description": "Grouped keywords associated with the search criteria."
},
"seedDomains": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of company domains you already know (if any)."
},
"assertions": {
"nullable": true,
"description": "Assumptions made during the search criteria generation process."
},
"constraints": {
"nullable": true,
"description": "Constraints applied to the search criteria generation process."
},
"locations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"country": {
"type": "string",
"nullable": true
},
"address": {
"type": "array",
"nullable": true,
"items": {
"type": "string"
}
},
"coordinates": {
"type": "array",
"nullable": true,
"items": {
"type": "number"
},
"minItems": 2,
"maxItems": 2
}
},
"required": ["country"]
},
"description": "List of country relevant to the study."
}
},
"required": ["userPrompt", "marketName", "marketType", "marketRole", "keywords", "locations"]
}
},
"required": ["searchCriteria"]
}
}
}
},
"responses": {
"200": {
"description": "Search criteria keywords generated",
"content": {
"application/json": {
"examples": {
"ai-transcription-response": {
"summary": "AI Transcription Services Response",
"description": "Example response for AI transcription services search",
"value": {
"metadata": {},
"data": [
"medical transcription software",
"healthcare AI transcription",
"enterprise clinical documentation",
"HIPAA compliant transcription services",
"medical voice recognition software",
"automated clinical notes",
"healthcare speech-to-text solutions",
"hospital dictation systems"
]
}
}
},
"schema": {
"type": "object",
"properties": {
"metadata": {
"type": "object",
"properties": {}
},
"data": {
"type": "array",
"items": {
"type": "string",
"description": "List of keywords for the search."
}
}
},
"required": ["metadata", "data"]
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"examples": {
"INVALID_INPUT": {
"value": {
"success": false,
"errorCode": "INVALID_INPUT",
"message": "Bad Request"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"401": {
"description": "Unauthorized - User not authenticated",
"content": {
"application/json": {
"examples": {
"UNAUTHORISED": {
"value": {
"success": false,
"errorCode": "UNAUTHORISED",
"message": "Unauthorized - User not authenticated"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"examples": {
"FORBIDDEN": {
"value": {
"success": false,
"errorCode": "FORBIDDEN",
"message": "Forbidden"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"examples": {
"INTERNAL_SERVER_ERROR": {
"value": {
"success": false,
"errorCode": "INTERNAL_SERVER_ERROR",
"message": "Internal Server Error"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
}
}
}
},
"/v2/discovery/{marketId}/search-criteria": {
"get": {
"tags": ["Discovery"],
"summary": "Get search criteria",
"description": "Retrieve the search criteria used for a specific market discovery.",
"parameters": [
{
"schema": {
"type": "integer",
"minimum": 0,
"exclusiveMinimum": true,
"description": "Unique identifier for the market study."
},
"required": true,
"description": "Unique identifier for the market study.",
"name": "marketId",
"in": "path"
}
],
"responses": {
"200": {
"description": "Search criteria retrieved",
"content": {
"application/json": {
"examples": {
"search-criteria-retrieved": {
"summary": "Search Criteria Retrieved",
"description": "Example response when retrieving search criteria for a market",
"value": {
"metadata": {},
"data": {
"marketName": "AI Healthcare Transcription Services",
"userPrompt": "Find AI-powered transcription services that serve enterprise healthcare customers",
"marketType": "service",
"marketRole": "serviceProvider",
"keywords": {
"features": ["AI transcription", "speech-to-text", "healthcare"],
"user": ["healthcare", "enterprise", "hospitals"],
"synonyms": ["transcription", "dictation", "voice-to-text"],
"irrelevant": ["manual transcription", "human transcription"]
},
"seedDomains": [],
"count": 50,
"assertions": null,
"constraints": null,
"projectKind": "first_pass",
"performSearch": true,
"locations": [
{
"country": "GB",
"address": ["123 Healthcare St", "Suite 100"],
"coordinates": [51.5074, -0.1278]
}
],
"createdAt": "2023-01-15T10:30:00Z"
}
}
}
},
"schema": {
"type": "object",
"properties": {
"metadata": {
"type": "object",
"properties": {}
},
"data": {
"type": "object",
"properties": {
"userPrompt": {
"type": "string",
"description": "Prompt used to generate the search criteria."
},
"marketName": {
"type": "string",
"description": "Name of the market associated with the study."
},
"marketType": {
"type": "string",
"enum": ["service", "product"],
"description": "Type classification of the market, such as region or category."
},
"marketRole": {
"type": "string",
"enum": [
"manufacturer",
"distributor",
"serviceProvider",
"service provider",
"consultant",
"provider"
],
"description": "\nTry to limit the companies to ones that fit a specific role in the market. Possible values are:\n\n- `\"manufacturer\"` – physical product manufacturing, e.g. a car manufacturer \n- `\"distributor\"` – physical product distribution, e.g. a car dealership \n- `\"service provider\"` – contractor or provider of pre-defined services, e.g. a car repair shop \n- `\"consultant\"` – consultants or advisers not themselves participating in the market, but offer advice to those who do, e.g. a motor regulatory consultant\n\nThis is a hint to the discovery process and does not guarantee that all returned companies will fit this role. If insufficient companies are found, the search will be broadened to include other roles.\n\nIf not provided, the AI will attempt to infer the role based on the market name, and assumes `\"manufacturer\"` if the market is too broad.\n\n> 💡 It is recommended to write your intended role in the market name, which the AI will be able to infer from. Supplying a `marketRole` incompatible with the market name might degrade the output.\n"
},
"keywords": {
"type": "object",
"properties": {
"features": {
"type": "array",
"items": {
"type": "string"
},
"description": "Keywords related to the market's features."
},
"user": {
"type": "array",
"items": {
"type": "string"
},
"description": "Keywords related to user preferences or behavior."
},
"synonyms": {
"type": "array",
"items": {
"type": "string"
},
"description": "Alternative terms related to the market search."
},
"irrelevant": {
"type": "array",
"items": {
"type": "string"
},
"description": "Terms identified as irrelevant for the search criteria."
}
},
"required": ["features", "user", "synonyms", "irrelevant"],
"description": "Grouped keywords associated with the search criteria."
},
"seedDomains": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of company domains you already know (if any)."
},
"assertions": {
"nullable": true,
"description": "Assumptions made during the search criteria generation process."
},
"constraints": {
"nullable": true,
"description": "Constraints applied to the search criteria generation process."
},
"locations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"country": {
"type": "string",
"nullable": true
},
"address": {
"type": "array",
"nullable": true,
"items": {
"type": "string"
}
},
"coordinates": {
"type": "array",
"nullable": true,
"items": {
"type": "number"
},
"minItems": 2,
"maxItems": 2
}
},
"required": ["country"]
},
"description": "List of country relevant to the study."
},
"marketId": {
"type": "number",
"description": "Unique identifier for the market study."
},
"jobId": {
"type": "string",
"nullable": true,
"description": "Unique identifier for the job associated with the study or agent in the format '::::'."
},
"projectKind": {
"type": "string",
"nullable": true,
"enum": ["first_pass", "second_pass", "manually_added", null],
"description": "Type of project associated with the search criteria."
},
"createdAt": {
"type": "string",
"nullable": true,
"format": "date-time",
"description": "Timestamp indicating when the record was created."
}
},
"required": [
"userPrompt",
"marketName",
"marketType",
"marketRole",
"keywords",
"locations",
"marketId",
"createdAt"
]
}
},
"required": ["metadata", "data"]
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"examples": {
"INVALID_INPUT": {
"value": {
"success": false,
"errorCode": "INVALID_INPUT",
"message": "Bad Request"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"examples": {
"FORBIDDEN": {
"value": {
"success": false,
"errorCode": "FORBIDDEN",
"message": "Forbidden"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"examples": {
"NOT_FOUND": {
"value": {
"success": false,
"errorCode": "NOT_FOUND",
"message": "Not Found"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"examples": {
"INTERNAL_SERVER_ERROR": {
"value": {
"success": false,
"errorCode": "INTERNAL_SERVER_ERROR",
"message": "Internal Server Error"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
}
}
}
},
"/v2/discovery/{marketId}/search-criteria/history": {
"get": {
"tags": ["Discovery"],
"summary": "Get search criteria history",
"description": "Retrieve the history of search criteria iterations for a specific market.",
"parameters": [
{
"schema": {
"type": "integer",
"minimum": 0,
"exclusiveMinimum": true,
"description": "Unique identifier for the market study."
},
"required": true,
"description": "Unique identifier for the market study.",
"name": "marketId",
"in": "path"
}
],
"responses": {
"200": {
"description": "Search criteria history retrieved",
"content": {
"application/json": {
"examples": {
"option-1": {
"summary": "Search Criteria History",
"description": "Example response showing search criteria history for a market",
"value": {
"metadata": {},
"data": [
{
"marketId": 12345,
"marketName": "AI Healthcare Transcription Services",
"userPrompt": "Find AI-powered transcription services that serve enterprise healthcare customers",
"marketType": "service",
"marketRole": "serviceProvider",
"keywords": {
"features": ["AI transcription", "speech-to-text", "healthcare"],
"user": ["healthcare", "enterprise", "hospitals"],
"synonyms": ["transcription", "dictation", "voice-to-text"],
"irrelevant": ["manual transcription", "human transcription"]
},
"count": 50,
"locations": [
{
"country": "GB",
"address": ["123 Healthcare St", "Suite 100"],
"coordinates": [51.5074, -0.1278]
}
],
"jobId": 12345,
"projectKind": "first_pass",
"performSearch": true,
"createdAt": "2023-01-15T10:30:00Z"
},
{
"marketId": 12345,
"marketName": "AI Transcription Services",
"userPrompt": "Find AI transcription services",
"marketType": "service",
"marketRole": "serviceProvider",
"keywords": {
"features": ["AI transcription", "speech-to-text"],
"user": ["enterprise"],
"synonyms": ["transcription", "dictation"],
"irrelevant": ["manual transcription"]
},
"count": 25,
"locations": [
{
"country": "GB",
"address": ["123 Healthcare St", "Suite 100"],
"coordinates": [51.5074, -0.1278]
}
],
"jobId": 12345,
"projectKind": "second_pass",
"performSearch": false,
"createdAt": "2023-01-15T10:30:00Z"
}
]
}
},
"option-2": {
"summary": "Search Criteria History",
"description": "Example response showing search criteria history for a market",
"value": {
"metadata": {},
"data": [
{
"marketId": 12345,
"marketName": "AI Healthcare Transcription Services",
"userPrompt": null,
"marketType": null,
"marketRole": null,
"keywords": null,
"seedDomains": null,
"assertions": null,
"constraints": null,
"locations": [
{
"country": "GB"
}
],
"jobId": null,
"projectKind": "first_pass",
"createdAt": "2023-01-15T10:30:00Z",
"count": null,
"performSearch": null
}
]
}
}
},
"schema": {
"type": "object",
"properties": {
"metadata": {
"type": "object",
"properties": {}
},
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"userPrompt": {
"type": "string",
"nullable": true,
"description": "Prompt used to generate the search criteria."
},
"marketName": {
"type": "string",
"description": "Name of the market associated with the study."
},
"marketType": {
"type": "string",
"nullable": true,
"enum": ["service", "product", null],
"description": "Type classification of the market, such as region or category."
},
"marketRole": {
"type": "string",
"nullable": true,
"enum": [
"manufacturer",
"distributor",
"serviceProvider",
"service provider",
"consultant",
"provider",
null
],
"description": "\nTry to limit the companies to ones that fit a specific role in the market. Possible values are:\n\n- `\"manufacturer\"` – physical product manufacturing, e.g. a car manufacturer \n- `\"distributor\"` – physical product distribution, e.g. a car dealership \n- `\"service provider\"` – contractor or provider of pre-defined services, e.g. a car repair shop \n- `\"consultant\"` – consultants or advisers not themselves participating in the market, but offer advice to those who do, e.g. a motor regulatory consultant\n\nThis is a hint to the discovery process and does not guarantee that all returned companies will fit this role. If insufficient companies are found, the search will be broadened to include other roles.\n\nIf not provided, the AI will attempt to infer the role based on the market name, and assumes `\"manufacturer\"` if the market is too broad.\n\n> 💡 It is recommended to write your intended role in the market name, which the AI will be able to infer from. Supplying a `marketRole` incompatible with the market name might degrade the output.\n"
},
"keywords": {
"type": "object",
"nullable": true,
"properties": {
"features": {
"type": "array",
"nullable": true,
"items": {
"type": "string"
},
"description": "Keywords related to the market's features."
},
"user": {
"type": "array",
"nullable": true,
"items": {
"type": "string"
},
"description": "Keywords related to user preferences or behavior."
},
"synonyms": {
"type": "array",
"nullable": true,
"items": {
"type": "string"
},
"description": "Alternative terms related to the market search."
},
"irrelevant": {
"type": "array",
"nullable": true,
"items": {
"type": "string"
},
"description": "Terms identified as irrelevant for the search criteria."
}
},
"required": ["features", "user", "synonyms", "irrelevant"],
"description": "Grouped keywords associated with the search criteria."
},
"seedDomains": {
"type": "array",
"nullable": true,
"items": {
"type": "string"
},
"description": "List of company domains you already know (if any)."
},
"assertions": {
"nullable": true,
"description": "Assumptions made during the search criteria generation process."
},
"constraints": {
"nullable": true,
"description": "Constraints applied to the search criteria generation process."
},
"locations": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"properties": {
"country": {
"type": "string",
"nullable": true
},
"address": {
"type": "array",
"nullable": true,
"items": {
"type": "string"
}
},
"coordinates": {
"type": "array",
"nullable": true,
"items": {
"type": "number"
},
"minItems": 2,
"maxItems": 2
}
},
"required": ["country"]
},
"description": "List of country relevant to the study."
},
"marketId": {
"type": "number",
"description": "Unique identifier for the market study."
},
"performSearch": {
"type": "boolean",
"nullable": true,
"description": "Indicates whether the search criteria should be used to perform a search."
},
"jobId": {
"type": "string",
"nullable": true,
"description": "Unique identifier for the job associated with the study or agent in the format '::::'."
},
"count": {
"type": "number",
"nullable": true,
"description": "Number of results returned for the search criteria."
},
"projectKind": {
"type": "string",
"nullable": true,
"enum": ["first_pass", "second_pass", "manually_added", null],
"description": "Type of project associated with the search criteria."
},
"pipelineChoices": {
"type": "object",
"properties": {
"skipDiscoveryReview": {
"type": "boolean",
"default": false,
"description": "Skip the discovery review step."
},
"runReverseGeocoding": {
"type": "boolean",
"default": true,
"description": "Run reverse geocoding step."
},
"runDunsMapper": {
"type": "boolean",
"default": true,
"description": "Run DUNS mapper step."
},
"runPeople": {
"type": "boolean",
"default": true,
"description": "Run people step."
},
"runNews": {
"type": "boolean",
"default": true,
"description": "Run news step."
},
"runEsg": {
"type": "boolean",
"default": true,
"description": "Run ESG step."
},
"runMomentumScore": {
"type": "boolean",
"default": true,
"description": "Run momentum score step."
},
"runMarketRadar": {
"type": "boolean",
"default": false,
"description": "Run market radar step."
},
"runTopicAnalysis": {
"type": "boolean",
"default": true,
"description": "Run topic analysis step."
},
"runPhraseExplorer": {
"type": "boolean",
"default": true,
"description": "Run phrase explorer step."
},
"runGenerateFeatureMap": {
"type": "boolean",
"default": true,
"description": "Run generate feature map step."
},
"sendPublishEmail": {
"type": "boolean",
"default": true,
"description": "Run send publish email step."
}
}
},
"createdAt": {
"type": "string",
"nullable": true,
"format": "date-time",
"description": "Timestamp indicating when the record was created."
}
},
"required": [
"userPrompt",
"marketName",
"marketRole",
"keywords",
"seedDomains",
"locations",
"marketId",
"performSearch",
"count",
"createdAt"
],
"description": "Search criteria history data. Fields from MongoDB will be populated, while fields from MySQL fallback will be null."
}
}
},
"required": ["metadata", "data"]
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"examples": {
"INVALID_INPUT": {
"value": {
"success": false,
"errorCode": "INVALID_INPUT",
"message": "Bad Request"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"examples": {
"FORBIDDEN": {
"value": {
"success": false,
"errorCode": "FORBIDDEN",
"message": "Forbidden"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"examples": {
"NOT_FOUND": {
"value": {
"success": false,
"errorCode": "NOT_FOUND",
"message": "Not Found"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"examples": {
"INTERNAL_SERVER_ERROR": {
"value": {
"success": false,
"errorCode": "INTERNAL_SERVER_ERROR",
"message": "Internal Server Error"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
}
}
}
},
"/v2/discovery/start": {
"post": {
"tags": ["Discovery"],
"summary": "Start discovery for new market",
"description": "Create a new market and initiate AI-powered company discovery process using structured search criteria.",
"parameters": [
{
"schema": {
"type": "number",
"nullable": true,
"description": "Unique identifier for the team to use for this discovery."
},
"required": false,
"description": "Unique identifier for the team to use for this discovery.",
"name": "teamId",
"in": "query"
},
{
"schema": {
"type": "number",
"nullable": true,
"description": "Unique identifier for the collection where the market will be created."
},
"required": false,
"description": "Unique identifier for the collection where the market will be created.",
"name": "collectionId",
"in": "query"
}
],
"requestBody": {
"content": {
"application/json": {
"examples": {
"ai-transcription-discovery": {
"summary": "AI Transcription Discovery",
"description": "Example for starting AI transcription services discovery",
"value": {
"searchCriteria": {
"marketName": "AI Healthcare Transcription Services",
"userPrompt": "Find AI-powered transcription services that serve enterprise healthcare customers",
"marketType": "service",
"marketRole": "serviceProvider",
"keywords": {
"features": ["AI transcription", "speech-to-text", "healthcare"],
"user": ["healthcare", "enterprise", "hospitals"],
"synonyms": ["transcription", "dictation", "voice-to-text"],
"irrelevant": ["manual transcription", "human transcription"]
},
"seedDomains": [],
"count": 50,
"assertions": null,
"constraints": null,
"performSearch": true,
"locations": [
{
"country": "GB",
"address": null,
"coordinates": null
}
]
}
}
}
},
"schema": {
"type": "object",
"properties": {
"searchCriteria": {
"type": "object",
"properties": {
"userPrompt": {
"type": "string",
"description": "Prompt used to generate the search criteria."
},
"marketName": {
"type": "string",
"description": "Name of the market associated with the study."
},
"marketType": {
"type": "string",
"enum": ["service", "product"],
"description": "Type classification of the market, such as region or category."
},
"marketRole": {
"type": "string",
"enum": [
"manufacturer",
"distributor",
"serviceProvider",
"service provider",
"consultant",
"provider"
],
"description": "\nTry to limit the companies to ones that fit a specific role in the market. Possible values are:\n\n- `\"manufacturer\"` – physical product manufacturing, e.g. a car manufacturer \n- `\"distributor\"` – physical product distribution, e.g. a car dealership \n- `\"service provider\"` – contractor or provider of pre-defined services, e.g. a car repair shop \n- `\"consultant\"` – consultants or advisers not themselves participating in the market, but offer advice to those who do, e.g. a motor regulatory consultant\n\nThis is a hint to the discovery process and does not guarantee that all returned companies will fit this role. If insufficient companies are found, the search will be broadened to include other roles.\n\nIf not provided, the AI will attempt to infer the role based on the market name, and assumes `\"manufacturer\"` if the market is too broad.\n\n> 💡 It is recommended to write your intended role in the market name, which the AI will be able to infer from. Supplying a `marketRole` incompatible with the market name might degrade the output.\n"
},
"keywords": {
"type": "object",
"properties": {
"features": {
"type": "array",
"items": {
"type": "string"
},
"description": "Keywords related to the market's features."
},
"user": {
"type": "array",
"items": {
"type": "string"
},
"description": "Keywords related to user preferences or behavior."
},
"synonyms": {
"type": "array",
"items": {
"type": "string"
},
"description": "Alternative terms related to the market search."
},
"irrelevant": {
"type": "array",
"items": {
"type": "string"
},
"description": "Terms identified as irrelevant for the search criteria."
}
},
"required": ["features", "user", "synonyms", "irrelevant"],
"description": "Grouped keywords associated with the search criteria."
},
"seedDomains": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of company domains you already know (if any)."
},
"assertions": {
"nullable": true,
"description": "Assumptions made during the search criteria generation process."
},
"constraints": {
"nullable": true,
"description": "Constraints applied to the search criteria generation process."
},
"locations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"country": {
"type": "string",
"nullable": true
},
"address": {
"type": "array",
"nullable": true,
"items": {
"type": "string"
}
},
"coordinates": {
"type": "array",
"nullable": true,
"items": {
"type": "number"
},
"minItems": 2,
"maxItems": 2
}
},
"required": ["country"]
},
"description": "List of country relevant to the study."
},
"count": {
"type": "number",
"default": 50,
"description": "Number of results returned for the search criteria."
},
"performSearch": {
"type": "boolean",
"default": true,
"description": "Indicates whether the search criteria should be used to perform a search."
}
},
"required": ["userPrompt", "marketName", "marketType", "marketRole", "keywords", "locations"]
},
"pipelineChoices": {
"type": "object",
"properties": {
"skipDiscoveryReview": {
"type": "boolean",
"default": false,
"description": "Skip the discovery review step."
},
"runReverseGeocoding": {
"type": "boolean",
"default": true,
"description": "Run reverse geocoding step."
},
"runDunsMapper": {
"type": "boolean",
"default": true,
"description": "Run DUNS mapper step."
},
"runPeople": {
"type": "boolean",
"default": true,
"description": "Run people step."
},
"runNews": {
"type": "boolean",
"default": true,
"description": "Run news step."
},
"runEsg": {
"type": "boolean",
"default": true,
"description": "Run ESG step."
},
"runMomentumScore": {
"type": "boolean",
"default": true,
"description": "Run momentum score step."
},
"runMarketRadar": {
"type": "boolean",
"default": false,
"description": "Run market radar step."
},
"runTopicAnalysis": {
"type": "boolean",
"default": true,
"description": "Run topic analysis step."
},
"runPhraseExplorer": {
"type": "boolean",
"default": true,
"description": "Run phrase explorer step."
},
"runGenerateFeatureMap": {
"type": "boolean",
"default": true,
"description": "Run generate feature map step."
},
"sendPublishEmail": {
"type": "boolean",
"default": true,
"description": "Run send publish email step."
}
}
}
},
"required": ["searchCriteria"]
}
}
}
},
"responses": {
"200": {
"description": "Discovery started successfully, returns the market ID and job IDs",
"content": {
"application/json": {
"examples": {
"discovery-started": {
"summary": "Discovery Started Response",
"description": "Example response when discovery is successfully started",
"value": {
"metadata": {
"marketId": 12345
},
"data": {
"jobIds": ["discovery-platform::python-first-pass::2026-01-07T11:26:50.406Z::04cda5"]
}
}
}
},
"schema": {
"type": "object",
"properties": {
"metadata": {
"type": "object",
"properties": {
"marketId": {
"type": "number",
"description": "Unique identifier for the market study."
}
},
"required": ["marketId"]
},
"data": {
"type": "object",
"properties": {
"jobIds": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of job IDs associated with the discovery process."
}
},
"required": ["jobIds"]
}
},
"required": ["metadata", "data"]
}
}
}
},
"400": {
"description": "Invalid input provided",
"content": {
"application/json": {
"examples": {
"INVALID_INPUT": {
"value": {
"success": false,
"errorCode": "INVALID_INPUT",
"message": "Invalid input provided"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"402": {
"description": "Payment Required - Team quota exceeded",
"content": {
"application/json": {
"examples": {
"QUOTA_EXCEEDED": {
"value": {
"success": false,
"errorCode": "QUOTA_EXCEEDED",
"message": "Payment Required - Team quota exceeded"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"examples": {
"FORBIDDEN": {
"value": {
"success": false,
"errorCode": "FORBIDDEN",
"message": "Forbidden"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"examples": {
"NOT_FOUND": {
"value": {
"success": false,
"errorCode": "NOT_FOUND",
"message": "Not Found"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"409": {
"description": "Conflict",
"content": {
"application/json": {
"examples": {
"CONFLICT": {
"value": {
"success": false,
"errorCode": "CONFLICT",
"message": "Conflict"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"examples": {
"INTERNAL_SERVER_ERROR": {
"value": {
"success": false,
"errorCode": "INTERNAL_SERVER_ERROR",
"message": "Internal Server Error"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
}
}
}
},
"/v2/discovery/{marketId}/start": {
"post": {
"tags": ["Discovery"],
"summary": "Start discovery for existing market",
"description": "Add more companies to an existing market using AI-powered discovery process.",
"parameters": [
{
"schema": {
"type": "number",
"nullable": true,
"description": "Unique identifier for the market study."
},
"required": false,
"description": "Unique identifier for the market study.",
"name": "marketId",
"in": "path"
},
{
"schema": {
"type": "number",
"nullable": true,
"description": "Unique identifier for the team to use for this discovery."
},
"required": false,
"description": "Unique identifier for the team to use for this discovery.",
"name": "teamId",
"in": "query"
},
{
"schema": {
"type": "number",
"nullable": true,
"description": "Unique identifier for the collection that the market belongs to."
},
"required": false,
"description": "Unique identifier for the collection that the market belongs to.",
"name": "collectionId",
"in": "query"
}
],
"requestBody": {
"content": {
"application/json": {
"examples": {
"ai-transcription-discovery": {
"summary": "AI Transcription Discovery",
"description": "Example for starting AI transcription services discovery",
"value": {
"searchCriteria": {
"marketName": "AI Healthcare Transcription Services",
"userPrompt": "Find AI-powered transcription services that serve enterprise healthcare customers",
"marketType": "service",
"marketRole": "serviceProvider",
"keywords": {
"features": ["AI transcription", "speech-to-text", "healthcare"],
"user": ["healthcare", "enterprise", "hospitals"],
"synonyms": ["transcription", "dictation", "voice-to-text"],
"irrelevant": ["manual transcription", "human transcription"]
},
"seedDomains": [],
"count": 50,
"assertions": null,
"constraints": null,
"performSearch": true,
"locations": [
{
"country": "GB",
"address": null,
"coordinates": null
}
]
}
}
}
},
"schema": {
"type": "object",
"properties": {
"searchCriteria": {
"type": "object",
"properties": {
"userPrompt": {
"type": "string",
"description": "Prompt used to generate the search criteria."
},
"marketName": {
"type": "string",
"description": "Name of the market associated with the study."
},
"marketType": {
"type": "string",
"enum": ["service", "product"],
"description": "Type classification of the market, such as region or category."
},
"marketRole": {
"type": "string",
"enum": [
"manufacturer",
"distributor",
"serviceProvider",
"service provider",
"consultant",
"provider"
],
"description": "\nTry to limit the companies to ones that fit a specific role in the market. Possible values are:\n\n- `\"manufacturer\"` – physical product manufacturing, e.g. a car manufacturer \n- `\"distributor\"` – physical product distribution, e.g. a car dealership \n- `\"service provider\"` – contractor or provider of pre-defined services, e.g. a car repair shop \n- `\"consultant\"` – consultants or advisers not themselves participating in the market, but offer advice to those who do, e.g. a motor regulatory consultant\n\nThis is a hint to the discovery process and does not guarantee that all returned companies will fit this role. If insufficient companies are found, the search will be broadened to include other roles.\n\nIf not provided, the AI will attempt to infer the role based on the market name, and assumes `\"manufacturer\"` if the market is too broad.\n\n> 💡 It is recommended to write your intended role in the market name, which the AI will be able to infer from. Supplying a `marketRole` incompatible with the market name might degrade the output.\n"
},
"keywords": {
"type": "object",
"properties": {
"features": {
"type": "array",
"items": {
"type": "string"
},
"description": "Keywords related to the market's features."
},
"user": {
"type": "array",
"items": {
"type": "string"
},
"description": "Keywords related to user preferences or behavior."
},
"synonyms": {
"type": "array",
"items": {
"type": "string"
},
"description": "Alternative terms related to the market search."
},
"irrelevant": {
"type": "array",
"items": {
"type": "string"
},
"description": "Terms identified as irrelevant for the search criteria."
}
},
"required": ["features", "user", "synonyms", "irrelevant"],
"description": "Grouped keywords associated with the search criteria."
},
"seedDomains": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of company domains you already know (if any)."
},
"assertions": {
"nullable": true,
"description": "Assumptions made during the search criteria generation process."
},
"constraints": {
"nullable": true,
"description": "Constraints applied to the search criteria generation process."
},
"locations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"country": {
"type": "string",
"nullable": true
},
"address": {
"type": "array",
"nullable": true,
"items": {
"type": "string"
}
},
"coordinates": {
"type": "array",
"nullable": true,
"items": {
"type": "number"
},
"minItems": 2,
"maxItems": 2
}
},
"required": ["country"]
},
"description": "List of country relevant to the study."
},
"count": {
"type": "number",
"default": 50,
"description": "Number of results returned for the search criteria."
},
"performSearch": {
"type": "boolean",
"default": true,
"description": "Indicates whether the search criteria should be used to perform a search."
}
},
"required": ["userPrompt", "marketName", "marketType", "marketRole", "keywords", "locations"]
},
"pipelineChoices": {
"type": "object",
"properties": {
"skipDiscoveryReview": {
"type": "boolean",
"default": false,
"description": "Skip the discovery review step."
},
"runReverseGeocoding": {
"type": "boolean",
"default": true,
"description": "Run reverse geocoding step."
},
"runDunsMapper": {
"type": "boolean",
"default": true,
"description": "Run DUNS mapper step."
},
"runPeople": {
"type": "boolean",
"default": true,
"description": "Run people step."
},
"runNews": {
"type": "boolean",
"default": true,
"description": "Run news step."
},
"runEsg": {
"type": "boolean",
"default": true,
"description": "Run ESG step."
},
"runMomentumScore": {
"type": "boolean",
"default": true,
"description": "Run momentum score step."
},
"runMarketRadar": {
"type": "boolean",
"default": false,
"description": "Run market radar step."
},
"runTopicAnalysis": {
"type": "boolean",
"default": true,
"description": "Run topic analysis step."
},
"runPhraseExplorer": {
"type": "boolean",
"default": true,
"description": "Run phrase explorer step."
},
"runGenerateFeatureMap": {
"type": "boolean",
"default": true,
"description": "Run generate feature map step."
},
"sendPublishEmail": {
"type": "boolean",
"default": true,
"description": "Run send publish email step."
}
}
}
},
"required": ["searchCriteria"]
}
}
}
},
"responses": {
"200": {
"description": "Discovery started successfully, returns the market ID and job IDs",
"content": {
"application/json": {
"examples": {
"discovery-started": {
"summary": "Discovery Started Response",
"description": "Example response when discovery is successfully started",
"value": {
"metadata": {
"marketId": 12345
},
"data": {
"jobIds": ["discovery-platform::python-second-pass::2026-01-07T11:26:50.406Z::04cda5"]
}
}
}
},
"schema": {
"type": "object",
"properties": {
"metadata": {
"type": "object",
"properties": {
"marketId": {
"type": "number",
"description": "Unique identifier for the market study."
}
},
"required": ["marketId"]
},
"data": {
"type": "object",
"properties": {
"jobIds": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of job IDs associated with the discovery process."
}
},
"required": ["jobIds"]
}
},
"required": ["metadata", "data"]
}
}
}
},
"400": {
"description": "Invalid input provided",
"content": {
"application/json": {
"examples": {
"INVALID_INPUT": {
"value": {
"success": false,
"errorCode": "INVALID_INPUT",
"message": "Invalid input provided"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"402": {
"description": "Payment Required - Team quota exceeded",
"content": {
"application/json": {
"examples": {
"QUOTA_EXCEEDED": {
"value": {
"success": false,
"errorCode": "QUOTA_EXCEEDED",
"message": "Payment Required - Team quota exceeded"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"examples": {
"FORBIDDEN": {
"value": {
"success": false,
"errorCode": "FORBIDDEN",
"message": "Forbidden"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"examples": {
"NOT_FOUND": {
"value": {
"success": false,
"errorCode": "NOT_FOUND",
"message": "Not Found"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"409": {
"description": "Conflict",
"content": {
"application/json": {
"examples": {
"CONFLICT": {
"value": {
"success": false,
"errorCode": "CONFLICT",
"message": "Conflict"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"examples": {
"INTERNAL_SERVER_ERROR": {
"value": {
"success": false,
"errorCode": "INTERNAL_SERVER_ERROR",
"message": "Internal Server Error"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
}
}
}
},
"/v2/discovery/{marketId}/companies/reviews": {
"patch": {
"tags": ["Discovery"],
"summary": "Update company review status",
"description": "Update the review status of discovered companies for quality control.",
"parameters": [
{
"schema": {
"type": "integer",
"minimum": 0,
"exclusiveMinimum": true,
"description": "Unique identifier for the market study."
},
"required": true,
"description": "Unique identifier for the market study.",
"name": "marketId",
"in": "path"
}
],
"requestBody": {
"content": {
"application/json": {
"examples": {
"update-all-companies": {
"summary": "Update All Companies",
"description": "Example for updating all companies",
"value": {
"reviewStatus": "include",
"target": {
"mode": "full"
}
}
},
"update-specific-companies": {
"summary": "Update Specific Companies",
"description": "Example for updating specific companies",
"value": {
"reviewStatus": "include",
"target": {
"mode": "partial",
"domains": ["new-company.com", "startup-ai.com"]
}
}
}
},
"schema": {
"type": "object",
"properties": {
"reviewStatus": {
"type": "string",
"enum": ["include", "exclude", "unreviewed"],
"description": "Review status of the company."
},
"target": {
"oneOf": [
{
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": ["partial"],
"description": "Review mode: 'partial' for selecting domains."
},
"domains": {
"type": "array",
"items": {
"type": "string"
},
"minItems": 1,
"description": "List of domains to update the review status for."
}
},
"required": ["mode", "domains"]
},
{
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": ["full"],
"description": "Review mode: 'full' for all domains."
}
},
"required": ["mode"]
}
]
}
},
"required": ["reviewStatus", "target"]
}
}
}
},
"responses": {
"200": {
"description": "Company review status updated",
"content": {
"application/json": {
"examples": {
"review-updated-full": {
"summary": "Review Status Updated",
"description": "Example response when company review status is updated for all companies",
"value": {
"metadata": {
"reviewStatus": "include",
"mode": "full"
},
"data": {
"updatedCount": 50
}
}
},
"review-updated-partial": {
"summary": "Review Status Updated",
"description": "Example response when company review status is updated for specific companies",
"value": {
"metadata": {
"reviewStatus": "include",
"mode": "partial"
},
"data": {
"updatedCount": 3
}
}
}
},
"schema": {
"type": "object",
"properties": {
"metadata": {
"type": "object",
"properties": {
"reviewStatus": {
"type": "string",
"enum": ["include", "exclude", "unreviewed"],
"description": "Review status of the company."
},
"mode": {
"type": "string",
"enum": ["partial", "full"],
"description": "Review mode: 'partial' for selecting domains."
}
},
"required": ["reviewStatus", "mode"]
},
"data": {
"type": "object",
"properties": {
"updatedCount": {
"type": "number",
"description": "Number of companies that had their review status updated."
}
},
"required": ["updatedCount"]
}
},
"required": ["metadata", "data"]
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"examples": {
"INVALID_INPUT": {
"value": {
"success": false,
"errorCode": "INVALID_INPUT",
"message": "Bad Request"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"examples": {
"FORBIDDEN": {
"value": {
"success": false,
"errorCode": "FORBIDDEN",
"message": "Forbidden"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"examples": {
"INTERNAL_SERVER_ERROR": {
"value": {
"success": false,
"errorCode": "INTERNAL_SERVER_ERROR",
"message": "Internal Server Error"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
}
}
}
},
"/v2/discovery/{marketId}/publish": {
"post": {
"tags": ["Discovery"],
"summary": "Publish a market",
"description": "Publish discovered companies and trigger comprehensive market analysis and enrichment.",
"parameters": [
{
"schema": {
"type": "integer",
"minimum": 0,
"exclusiveMinimum": true,
"description": "Unique identifier for the market study."
},
"required": true,
"description": "Unique identifier for the market study.",
"name": "marketId",
"in": "path"
},
{
"schema": {
"type": "number",
"nullable": true,
"description": "Unique identifier for the team."
},
"required": false,
"description": "Unique identifier for the team.",
"name": "teamId",
"in": "query"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"anyOf": [
{
"type": "object",
"properties": {
"pipelineChoices": {
"type": "object",
"properties": {
"skipDiscoveryReview": {
"type": "boolean",
"default": false,
"description": "Skip the discovery review step."
},
"runReverseGeocoding": {
"type": "boolean",
"default": true,
"description": "Run reverse geocoding step."
},
"runDunsMapper": {
"type": "boolean",
"default": true,
"description": "Run DUNS mapper step."
},
"runPeople": {
"type": "boolean",
"default": true,
"description": "Run people step."
},
"runNews": {
"type": "boolean",
"default": true,
"description": "Run news step."
},
"runEsg": {
"type": "boolean",
"default": true,
"description": "Run ESG step."
},
"runMomentumScore": {
"type": "boolean",
"default": true,
"description": "Run momentum score step."
},
"runMarketRadar": {
"type": "boolean",
"default": false,
"description": "Run market radar step."
},
"runTopicAnalysis": {
"type": "boolean",
"default": true,
"description": "Run topic analysis step."
},
"runPhraseExplorer": {
"type": "boolean",
"default": true,
"description": "Run phrase explorer step."
},
"runGenerateFeatureMap": {
"type": "boolean",
"default": true,
"description": "Run generate feature map step."
},
"sendPublishEmail": {
"type": "boolean",
"default": true,
"description": "Run send publish email step."
}
}
}
}
},
{
"nullable": true
}
]
}
}
}
},
"responses": {
"200": {
"description": "Publish a market in discovery workflow response",
"content": {
"application/json": {
"examples": {
"publish-success": {
"summary": "Publish Success Response",
"description": "Example response when market is successfully published",
"value": {
"metadata": {
"marketId": 12345
},
"data": {
"jobIds": [
"publish-platform::publish-study::2026-01-07T11:26:50.406Z::04cda5",
"publish-platform::python-scrape::2026-01-07T11:26:50.406Z::b12a9f",
"publish-platform::python-web-traffic::2026-01-07T11:26:50.406Z::c07be2"
]
}
}
}
},
"schema": {
"type": "object",
"properties": {
"metadata": {
"type": "object",
"properties": {
"marketId": {
"type": "number",
"description": "Unique identifier for the market study."
}
},
"required": ["marketId"]
},
"data": {
"type": "object",
"properties": {
"jobIds": {
"type": "array",
"items": {
"type": "string",
"description": "Unique identifier for the job associated with the study or agent in the format '::::'."
},
"description": "List of publish job IDs associated with the market."
}
},
"required": ["jobIds"]
}
},
"required": ["metadata", "data"]
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"examples": {
"INVALID_INPUT": {
"value": {
"success": false,
"errorCode": "INVALID_INPUT",
"message": "Bad Request"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"examples": {
"FORBIDDEN": {
"value": {
"success": false,
"errorCode": "FORBIDDEN",
"message": "Forbidden"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"examples": {
"NOT_FOUND": {
"value": {
"success": false,
"errorCode": "NOT_FOUND",
"message": "Not Found"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"examples": {
"INTERNAL_SERVER_ERROR": {
"value": {
"success": false,
"errorCode": "INTERNAL_SERVER_ERROR",
"message": "Internal Server Error"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
}
}
}
},
"/v2/discovery/{marketId}/jobs": {
"get": {
"tags": ["Discovery"],
"summary": "Get job status",
"description": "Retrieve the status and progress of discovery jobs for a given market, optionally filtered by job IDs and/or status.",
"parameters": [
{
"schema": {
"type": "integer",
"minimum": 0,
"exclusiveMinimum": true,
"description": "Unique identifier for the market study."
},
"required": true,
"description": "Unique identifier for the market study.",
"name": "marketId",
"in": "path"
},
{
"schema": {
"type": "number",
"nullable": true,
"description": "Unique identifier for the team."
},
"required": false,
"description": "Unique identifier for the team.",
"name": "teamId",
"in": "query"
},
{
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
}
],
"description": "Filter by specific job IDs. Can be repeated for multiple values."
},
"required": false,
"description": "Filter by specific job IDs. Can be repeated for multiple values.",
"name": "jobIds",
"in": "query"
},
{
"schema": {
"anyOf": [
{
"type": "string",
"enum": ["queued", "running", "stuck", "completed", "failed"]
},
{
"type": "array",
"items": {
"type": "string",
"enum": ["queued", "running", "stuck", "completed", "failed"]
}
}
],
"description": "Filter by job status. Can be repeated for multiple values."
},
"required": false,
"description": "Filter by job status. Can be repeated for multiple values.",
"name": "status",
"in": "query"
}
],
"responses": {
"200": {
"description": "Job status retrieved",
"content": {
"application/json": {
"examples": {
"job-in-progress": {
"summary": "Discovery In Progress",
"description": "Example response when job is still running",
"value": {
"metadata": {
"marketId": 12345
},
"data": [
{
"jobId": "discovery-platform::python-first-pass::2026-01-07T11:26:50.406Z::04cda5",
"status": "running",
"workflowName": "python-first-pass",
"progress": 65,
"startTime": "2024-01-15T10:30:00Z",
"endTime": null
},
{
"jobId": "discovery-platform::python-second-pass::2026-01-07T11:26:50.406Z::b12a9f",
"status": "running",
"workflowName": "python-second-pass",
"progress": 0,
"startTime": "2024-01-15T10:30:00Z",
"endTime": null
}
]
}
},
"job-completed": {
"summary": "Discovery Completed",
"description": "Example response when job has finished",
"value": {
"metadata": {
"marketId": 12345
},
"data": [
{
"jobId": "discovery-platform::python-first-pass::2026-01-07T11:26:50.406Z::04cda5",
"status": "completed",
"workflowName": "python-first-pass",
"progress": 100,
"startTime": "2024-01-15T10:30:00Z",
"endTime": "2024-01-15T10:45:00Z"
},
{
"jobId": "discovery-platform::python-second-pass::2026-01-07T11:26:50.406Z::b12a9f",
"status": "completed",
"workflowName": "python-second-pass",
"progress": 100,
"startTime": "2024-01-15T10:45:00Z",
"endTime": "2024-01-15T11:00:00Z"
}
]
}
}
},
"schema": {
"type": "object",
"properties": {
"metadata": {
"type": "object",
"properties": {
"marketId": {
"type": "integer",
"minimum": 0,
"exclusiveMinimum": true,
"description": "Unique identifier for the market study."
}
},
"required": ["marketId"]
},
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"jobId": {
"type": "string",
"description": "Unique identifier for the job associated with the study or agent in the format '::::'."
},
"progress": {
"type": "number",
"description": "Progress percentage of the job."
},
"workflowName": {
"type": "string",
"description": "Workflow name associated with the job."
},
"status": {
"type": "string",
"enum": ["queued", "running", "stuck", "completed", "failed"],
"description": "Status of the job."
},
"startTime": {
"type": "string",
"format": "date-time",
"description": "Timestamp indicating when the job started."
},
"endTime": {
"type": "string",
"nullable": true,
"format": "date-time",
"description": "Timestamp indicating when the job ended."
}
},
"required": ["jobId", "progress", "workflowName", "status", "startTime", "endTime"]
}
}
},
"required": ["metadata", "data"]
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"examples": {
"INVALID_INPUT": {
"value": {
"success": false,
"errorCode": "INVALID_INPUT",
"message": "Bad Request"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"examples": {
"FORBIDDEN": {
"value": {
"success": false,
"errorCode": "FORBIDDEN",
"message": "Forbidden"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"examples": {
"NOT_FOUND": {
"value": {
"success": false,
"errorCode": "NOT_FOUND",
"message": "Not Found"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"examples": {
"INTERNAL_SERVER_ERROR": {
"value": {
"success": false,
"errorCode": "INTERNAL_SERVER_ERROR",
"message": "Internal Server Error"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
}
}
}
},
"/v2/collections/{collectionId}/markets": {
"get": {
"tags": ["Markets"],
"summary": "Get markets",
"description": "Fetch list of markets in the collection with pagination and filtering",
"parameters": [
{
"schema": {
"type": "integer",
"minimum": 0,
"exclusiveMinimum": true,
"description": "ID of the collection to which the markets belong."
},
"required": true,
"description": "ID of the collection to which the markets belong.",
"name": "collectionId",
"in": "path"
},
{
"schema": {
"type": "string",
"description": "Search markets by id, name, or description."
},
"required": false,
"description": "Search markets by id, name, or description.",
"name": "search",
"in": "query"
},
{
"schema": {
"type": "integer",
"minimum": 0,
"exclusiveMinimum": true,
"default": 1,
"description": "Page number to retrieve, starting from 1."
},
"required": false,
"description": "Page number to retrieve, starting from 1.",
"name": "page",
"in": "query"
},
{
"schema": {
"type": "integer",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 100,
"default": 50,
"description": "Number of markets per page."
},
"required": false,
"description": "Number of markets per page.",
"name": "pageSize",
"in": "query"
},
{
"schema": {
"type": "string",
"enum": ["id", "name", "createdAt", "updatedAt", "status"],
"default": "createdAt",
"description": "Field to sort markets by. Default is createdAt."
},
"required": false,
"description": "Field to sort markets by. Default is createdAt.",
"name": "sortBy",
"in": "query"
},
{
"schema": {
"type": "string",
"enum": ["asc", "desc"],
"default": "desc",
"description": "Order of sorting. Default is desc."
},
"required": false,
"description": "Order of sorting. Default is desc.",
"name": "sortOrder",
"in": "query"
},
{
"schema": {
"type": "boolean",
"nullable": true,
"default": false,
"description": "Filter markets by archived status."
},
"required": false,
"description": "Filter markets by archived status.",
"name": "isArchived",
"in": "query"
},
{
"schema": {
"type": "string",
"enum": ["draft", "publishing", "published"],
"description": "Filter markets by status."
},
"required": false,
"description": "Filter markets by status.",
"name": "status",
"in": "query"
}
],
"responses": {
"200": {
"description": "List markets in collection response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"metadata": {
"type": "object",
"properties": {
"pagination": {
"type": "object",
"properties": {
"totalItems": {
"type": "number",
"description": "Total number of items for the returned dataset after filtering."
},
"totalPages": {
"type": "number",
"description": "Total number of pages for the returned dataset after filtering."
},
"currentPage": {
"type": "number",
"description": "Current page number."
},
"pageSize": {
"type": "number",
"description": "Number of items per page."
},
"unfilteredTotalItems": {
"type": "number",
"description": "Total number of items for the original dataset before filtering."
},
"unfilteredTotalPages": {
"type": "number",
"description": "Total number of pages for the original dataset before filtering."
}
},
"required": ["totalItems", "totalPages", "currentPage", "pageSize"],
"description": "Schema for pagination metadata, including total items, total pages, current page, and page size.",
"example": {
"totalItems": 123,
"totalPages": 13,
"currentPage": 1,
"pageSize": 10,
"unfilteredTotalItems": 196,
"unfilteredTotalPages": 20
}
},
"filters": {
"type": "object",
"properties": {
"isArchived": {
"type": "boolean",
"description": "Indicates whether the results are filtered by archived status."
}
},
"required": ["isArchived"]
},
"sort": {
"type": "object",
"properties": {
"field": {
"type": "string",
"enum": ["id", "name", "createdAt", "updatedAt", "status"]
},
"order": {
"type": "string",
"enum": ["asc", "desc"]
}
},
"required": ["field", "order"]
}
},
"required": ["pagination", "filters", "sort"]
},
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "Unique identifier of the market."
},
"name": {
"type": "string",
"description": "Name of the market."
},
"description": {
"type": "string",
"nullable": true,
"description": "Optional description of the market."
},
"headerImage": {
"type": "string",
"nullable": true,
"description": "Optional URL to the market's header image."
},
"status": {
"type": "string",
"nullable": true,
"description": "Optional status of the market."
},
"isEditable": {
"type": "boolean",
"nullable": true,
"description": "Indicates if the market is editable."
},
"isArchived": {
"type": "boolean",
"nullable": true,
"description": "Indicates if the market is archived."
},
"createdAt": {
"type": "string",
"nullable": true,
"format": "date-time",
"description": "Timestamp when the market was created."
},
"updatedAt": {
"type": "string",
"nullable": true,
"format": "date-time",
"description": "Timestamp when the market was last updated."
},
"companyCounts": {
"type": "object",
"properties": {
"published": {
"type": "number",
"nullable": true,
"description": "Number of published companies in the market."
},
"discovery": {
"type": "object",
"nullable": true,
"properties": {
"total": {
"type": "number",
"description": "Total distinct companies discovered in the market."
},
"include": {
"type": "number",
"description": "Companies marked for inclusion during discovery."
},
"unreviewed": {
"type": "number",
"description": "Companies awaiting review during discovery."
}
},
"required": ["total", "include", "unreviewed"],
"description": "Discovery-stage company counts. Null when no companies have been discovered."
}
},
"required": ["published", "discovery"]
},
"collections": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "integer",
"minimum": 0,
"exclusiveMinimum": true,
"description": "ID of the collection."
},
"name": {
"type": "string",
"nullable": true,
"description": "Name of the collection."
}
},
"required": ["id", "name"]
},
"description": "Collections the market belongs to within the caller's accessible scope."
},
"createdBy": {
"type": "object",
"nullable": true,
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "User ID."
},
"fullName": {
"type": "string",
"nullable": true,
"description": "Display name of the user."
}
},
"required": ["id", "fullName"],
"description": "Market creator, derived from the earliest discovery search record."
}
},
"required": [
"id",
"name",
"description",
"headerImage",
"status",
"isEditable",
"isArchived",
"createdAt",
"updatedAt",
"companyCounts",
"createdBy"
]
}
}
},
"required": ["metadata", "data"]
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"examples": {
"INVALID_INPUT": {
"value": {
"success": false,
"errorCode": "INVALID_INPUT",
"message": "Bad Request"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"403": {
"description": "Forbidden - You do not have access to this collection",
"content": {
"application/json": {
"examples": {
"FORBIDDEN": {
"value": {
"success": false,
"errorCode": "FORBIDDEN",
"message": "Forbidden - You do not have access to this collection"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"404": {
"description": "Not Found - Markets not found",
"content": {
"application/json": {
"examples": {
"NOT_FOUND": {
"value": {
"success": false,
"errorCode": "NOT_FOUND",
"message": "Not Found - Markets not found"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"examples": {
"INTERNAL_SERVER_ERROR": {
"value": {
"success": false,
"errorCode": "INTERNAL_SERVER_ERROR",
"message": "Internal Server Error"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
}
}
},
"post": {
"tags": ["Markets"],
"summary": "Create a market",
"description": "Create a new market in the collection",
"parameters": [
{
"schema": {
"type": "integer",
"minimum": 0,
"exclusiveMinimum": true,
"description": "ID of the collection where the new market will be created."
},
"required": true,
"description": "ID of the collection where the new market will be created.",
"name": "collectionId",
"in": "path"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Name of the new market."
},
"subtitle": {
"type": "string",
"description": "Subtitle of the new market."
},
"description": {
"type": "string",
"description": "Description of the new market."
},
"thumbnailSrc": {
"type": "string",
"description": "URL to the new market's header image."
}
},
"required": ["name"]
}
}
}
},
"responses": {
"200": {
"description": "Create a market in collection response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"description": "Indicates whether the creation operation was successful."
},
"message": {
"type": "string",
"description": "Optional message providing additional information about the creation operation."
},
"marketId": {
"type": "number",
"description": "Unique identifier of the newly created market."
}
},
"required": ["success", "message", "marketId"]
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"examples": {
"INVALID_INPUT": {
"value": {
"success": false,
"errorCode": "INVALID_INPUT",
"message": "Bad Request"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"403": {
"description": "Forbidden - You do not have access to this collection",
"content": {
"application/json": {
"examples": {
"FORBIDDEN": {
"value": {
"success": false,
"errorCode": "FORBIDDEN",
"message": "Forbidden - You do not have access to this collection"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"examples": {
"INTERNAL_SERVER_ERROR": {
"value": {
"success": false,
"errorCode": "INTERNAL_SERVER_ERROR",
"message": "Internal Server Error"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
}
}
}
},
"/v2/markets/{marketId}": {
"get": {
"tags": ["Markets"],
"summary": "Get a market",
"description": "Fetch a specific market in the collection",
"parameters": [
{
"schema": {
"type": "integer",
"minimum": 0,
"exclusiveMinimum": true,
"description": "ID of the specific market."
},
"required": true,
"description": "ID of the specific market.",
"name": "marketId",
"in": "path"
}
],
"responses": {
"200": {
"description": "GET a market in collection response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "object",
"properties": {
"id": {
"type": "number",
"description": "Unique identifier of the market."
},
"name": {
"type": "string",
"description": "Name of the market."
},
"description": {
"type": "string",
"nullable": true,
"description": "Optional description of the market."
},
"headerImage": {
"type": "string",
"nullable": true,
"description": "Optional URL to the market's header image."
},
"status": {
"type": "string",
"nullable": true,
"description": "Optional status of the market."
},
"isEditable": {
"type": "boolean",
"nullable": true,
"description": "Indicates if the market is editable."
},
"isArchived": {
"type": "boolean",
"nullable": true,
"description": "Indicates if the market is archived."
},
"createdAt": {
"type": "string",
"nullable": true,
"format": "date-time",
"description": "Timestamp when the market was created."
},
"updatedAt": {
"type": "string",
"nullable": true,
"format": "date-time",
"description": "Timestamp when the market was last updated."
},
"pendingReviewRequestedAt": {
"type": "string",
"nullable": true,
"format": "date-time",
"description": "Timestamp of the open manual-review request, or null if none is pending."
}
},
"required": [
"id",
"name",
"description",
"headerImage",
"status",
"isEditable",
"isArchived",
"createdAt",
"updatedAt",
"pendingReviewRequestedAt"
]
}
},
"required": ["data"]
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"examples": {
"INVALID_INPUT": {
"value": {
"success": false,
"errorCode": "INVALID_INPUT",
"message": "Bad Request"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"403": {
"description": "Forbidden - You do not have access to this market",
"content": {
"application/json": {
"examples": {
"FORBIDDEN": {
"value": {
"success": false,
"errorCode": "FORBIDDEN",
"message": "Forbidden - You do not have access to this market"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"404": {
"description": "Not Found - Market not found",
"content": {
"application/json": {
"examples": {
"NOT_FOUND": {
"value": {
"success": false,
"errorCode": "NOT_FOUND",
"message": "Not Found - Market not found"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"examples": {
"INTERNAL_SERVER_ERROR": {
"value": {
"success": false,
"errorCode": "INTERNAL_SERVER_ERROR",
"message": "Internal Server Error"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
}
}
},
"patch": {
"tags": ["Markets"],
"summary": "Update a market",
"description": "Update a specific market in the collection",
"parameters": [
{
"schema": {
"type": "integer",
"minimum": 0,
"exclusiveMinimum": true,
"description": "ID of the market to update."
},
"required": true,
"description": "ID of the market to update.",
"name": "marketId",
"in": "path"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Updated name of the market."
},
"description": {
"type": "string",
"nullable": true,
"description": "Updated description of the market. Can be set to null to clear the description."
},
"headerImage": {
"type": "string",
"description": "Updated URL to the market's header image."
}
}
}
}
}
},
"responses": {
"200": {
"description": "Update a market in collection response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"description": "Indicates whether the update operation was successful."
},
"message": {
"type": "string",
"description": "Optional message providing additional information about the update operation."
}
},
"required": ["success", "message"]
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"examples": {
"INVALID_INPUT": {
"value": {
"success": false,
"errorCode": "INVALID_INPUT",
"message": "Bad Request"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"403": {
"description": "Forbidden - You do not have access to this market",
"content": {
"application/json": {
"examples": {
"FORBIDDEN": {
"value": {
"success": false,
"errorCode": "FORBIDDEN",
"message": "Forbidden - You do not have access to this market"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"404": {
"description": "Not Found - Market not found",
"content": {
"application/json": {
"examples": {
"NOT_FOUND": {
"value": {
"success": false,
"errorCode": "NOT_FOUND",
"message": "Not Found - Market not found"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"examples": {
"INTERNAL_SERVER_ERROR": {
"value": {
"success": false,
"errorCode": "INTERNAL_SERVER_ERROR",
"message": "Internal Server Error"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
}
}
},
"delete": {
"tags": ["Markets"],
"summary": "Delete a market",
"description": "Delete a specific market in the collection",
"parameters": [
{
"schema": {
"type": "integer",
"minimum": 0,
"exclusiveMinimum": true,
"description": "ID of the market to delete."
},
"required": true,
"description": "ID of the market to delete.",
"name": "marketId",
"in": "path"
}
],
"responses": {
"200": {
"description": "Delete a market in collection response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"description": "Indicates whether the deletion was successful."
},
"message": {
"type": "string",
"description": "Optional message providing additional information about the deletion."
}
},
"required": ["success", "message"]
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"examples": {
"INVALID_INPUT": {
"value": {
"success": false,
"errorCode": "INVALID_INPUT",
"message": "Bad Request"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"403": {
"description": "Forbidden - You do not have access to this market",
"content": {
"application/json": {
"examples": {
"FORBIDDEN": {
"value": {
"success": false,
"errorCode": "FORBIDDEN",
"message": "Forbidden - You do not have access to this market"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"404": {
"description": "Not Found - Market not found",
"content": {
"application/json": {
"examples": {
"NOT_FOUND": {
"value": {
"success": false,
"errorCode": "NOT_FOUND",
"message": "Not Found - Market not found"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"409": {
"description": "Conflict - A manual review is pending for this market",
"content": {
"application/json": {
"examples": {
"REVIEW_PENDING": {
"value": {
"success": false,
"errorCode": "REVIEW_PENDING",
"message": "Conflict - A manual review is pending for this market"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"examples": {
"INTERNAL_SERVER_ERROR": {
"value": {
"success": false,
"errorCode": "INTERNAL_SERVER_ERROR",
"message": "Internal Server Error"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
}
}
}
},
"/v2/markets/{marketId}/move": {
"post": {
"tags": ["Markets"],
"summary": "Move a market",
"description": "Move a specific market in the collection",
"parameters": [
{
"schema": {
"type": "integer",
"minimum": 0,
"exclusiveMinimum": true,
"description": "ID of the market to move."
},
"required": true,
"description": "ID of the market to move.",
"name": "marketId",
"in": "path"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"oldCollectionId": {
"type": "integer",
"minimum": 0,
"exclusiveMinimum": true,
"description": "ID of the current collection where the market is located."
},
"newCollectionId": {
"type": "integer",
"minimum": 0,
"exclusiveMinimum": true,
"description": "ID of the target collection where the market will be moved."
}
},
"required": ["oldCollectionId", "newCollectionId"]
}
}
}
},
"responses": {
"200": {
"description": "Move a market in collection response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"description": "Indicates whether the move operation was successful."
},
"message": {
"type": "string",
"description": "Optional message providing additional information about the move operation."
}
},
"required": ["success", "message"]
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"examples": {
"INVALID_INPUT": {
"value": {
"success": false,
"errorCode": "INVALID_INPUT",
"message": "Bad Request"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"403": {
"description": "Forbidden - You do not have access to this market",
"content": {
"application/json": {
"examples": {
"FORBIDDEN": {
"value": {
"success": false,
"errorCode": "FORBIDDEN",
"message": "Forbidden - You do not have access to this market"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"404": {
"description": "Not Found - Market not found",
"content": {
"application/json": {
"examples": {
"NOT_FOUND": {
"value": {
"success": false,
"errorCode": "NOT_FOUND",
"message": "Not Found - Market not found"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"409": {
"description": "Conflict - A manual review is pending for this market",
"content": {
"application/json": {
"examples": {
"REVIEW_PENDING": {
"value": {
"success": false,
"errorCode": "REVIEW_PENDING",
"message": "Conflict - A manual review is pending for this market"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"examples": {
"INTERNAL_SERVER_ERROR": {
"value": {
"success": false,
"errorCode": "INTERNAL_SERVER_ERROR",
"message": "Internal Server Error"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
}
}
}
},
"/v2/markets/{marketId}/explorer/companies": {
"get": {
"tags": ["Markets"],
"summary": "List market explorer companies",
"description": "List the companies in a published market, intended for Market Explorer use. \n Differs from a draft study by having company metadata populated, and having completed a detailed scrape.",
"parameters": [
{
"schema": {
"type": "integer",
"minimum": 0,
"exclusiveMinimum": true,
"description": "ID of the market whose explorer companies will be retrieved."
},
"required": true,
"description": "ID of the market whose explorer companies will be retrieved.",
"name": "marketId",
"in": "path"
},
{
"schema": {
"type": "integer",
"minimum": 0,
"exclusiveMinimum": true,
"description": "Unique identifier for the team used to access the market, for determining access rights and blacklists.\n Team ID can be provided either in path or query parameter for backward compatibility; exactly one is required."
},
"required": false,
"description": "Unique identifier for the team used to access the market, for determining access rights and blacklists.\n Team ID can be provided either in path or query parameter for backward compatibility; exactly one is required.",
"name": "teamId",
"in": "path"
},
{
"schema": {
"type": "integer",
"minimum": 0,
"exclusiveMinimum": true,
"description": "Unique identifier for the team used to access the market, for determining access rights and blacklists.\n Team ID can be provided either in path or query parameter for backward compatibility; exactly one is required."
},
"required": false,
"description": "Unique identifier for the team used to access the market, for determining access rights and blacklists.\n Team ID can be provided either in path or query parameter for backward compatibility; exactly one is required.",
"name": "teamId",
"in": "query"
},
{
"schema": {
"type": "string",
"description": "Search term to filter companies by name, or description."
},
"required": false,
"description": "Search term to filter companies by name, or description.",
"name": "search",
"in": "query"
},
{
"schema": {
"type": "array",
"items": {
"type": "string"
}
},
"required": false,
"name": "domains",
"in": "query"
},
{
"schema": {
"type": "array",
"items": {
"type": "string"
}
},
"required": false,
"name": "categories",
"in": "query"
},
{
"schema": {
"type": "array",
"items": {
"type": "string"
}
},
"required": false,
"name": "userTags",
"in": "query"
},
{
"schema": {
"type": "boolean",
"nullable": true
},
"required": false,
"name": "favourites",
"in": "query"
},
{
"schema": {
"type": "array",
"items": {
"type": "string"
}
},
"required": false,
"name": "topics",
"in": "query"
},
{
"schema": {
"type": "array",
"items": {
"type": "string"
},
"description": "Filter by feature architecture node IDs. Prefix with 'e:' to exclude (e.g., '1, 2, e:3')."
},
"required": false,
"description": "Filter by feature architecture node IDs. Prefix with 'e:' to exclude (e.g., '1, 2, e:3').",
"name": "features",
"in": "query"
},
{
"schema": {
"type": "array",
"items": {
"type": "string"
}
},
"required": false,
"name": "size",
"in": "query"
},
{
"schema": {
"type": "array",
"items": {
"type": "string"
}
},
"required": false,
"name": "revenueRange",
"in": "query"
},
{
"schema": {
"type": "boolean",
"nullable": true
},
"required": false,
"name": "isLocationVerified",
"in": "query"
},
{
"schema": {
"type": "array",
"items": {
"type": "string"
}
},
"required": false,
"name": "hqCountry",
"in": "query"
},
{
"schema": {
"type": "array",
"items": {
"type": "string"
}
},
"required": false,
"name": "hqState",
"in": "query"
},
{
"schema": {
"type": "array",
"items": {
"type": "string"
}
},
"required": false,
"name": "hqCity",
"in": "query"
},
{
"schema": {
"type": "array",
"items": {
"type": "string"
}
},
"required": false,
"name": "phrases",
"in": "query"
},
{
"schema": {
"type": "object",
"properties": {
"min": {
"type": "integer",
"minimum": 0,
"maximum": 100
},
"max": {
"type": "integer",
"minimum": 0,
"maximum": 100
}
},
"required": ["min", "max"]
},
"required": false,
"name": "momentumScoreRange",
"in": "query"
},
{
"schema": {
"type": "object",
"properties": {
"min": {
"type": "integer",
"minimum": 1700,
"maximum": 2026
},
"max": {
"type": "integer",
"minimum": 1700,
"maximum": 2026
}
},
"required": ["min", "max"]
},
"required": false,
"name": "foundedYearRange",
"in": "query"
},
{
"schema": {
"type": "integer",
"minimum": 0,
"exclusiveMinimum": true,
"default": 1,
"description": "Page number to retrieve, starting from 1."
},
"required": false,
"description": "Page number to retrieve, starting from 1.",
"name": "page",
"in": "query"
},
{
"schema": {
"type": "integer",
"minimum": 0,
"exclusiveMinimum": true,
"maximum": 500,
"default": 50,
"description": "Number of companies per page."
},
"required": false,
"description": "Number of companies per page.",
"name": "pageSize",
"in": "query"
},
{
"schema": {
"type": "object",
"properties": {
"field": {
"type": "string",
"enum": [
"name",
"domain",
"companySize",
"companyRevenue",
"yearFounded",
"numberOfLocations",
"hqCountry",
"hqState",
"hqCity",
"momentumScore",
"starred"
]
},
"order": {
"type": "string",
"enum": ["asc", "desc"]
}
},
"required": ["field", "order"]
},
"required": false,
"name": "sort",
"in": "query"
},
{
"schema": {
"type": "string",
"description": "Filter companies by version date."
},
"required": false,
"description": "Filter companies by version date.",
"name": "versionDate",
"in": "query"
}
],
"responses": {
"200": {
"description": "Market explorer companies response schema",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"metadata": {
"type": "object",
"properties": {
"pagination": {
"type": "object",
"properties": {
"totalItems": {
"type": "number",
"description": "Total number of items for the returned dataset after filtering."
},
"totalPages": {
"type": "number",
"description": "Total number of pages for the returned dataset after filtering."
},
"currentPage": {
"type": "number",
"description": "Current page number."
},
"pageSize": {
"type": "number",
"description": "Number of items per page."
},
"unfilteredTotalItems": {
"type": "number",
"description": "Total number of items for the original dataset before filtering."
},
"unfilteredTotalPages": {
"type": "number",
"description": "Total number of pages for the original dataset before filtering."
}
},
"required": ["totalItems", "totalPages", "currentPage", "pageSize"],
"description": "Schema for pagination metadata, including total items, total pages, current page, and page size.",
"example": {
"totalItems": 123,
"totalPages": 13,
"currentPage": 1,
"pageSize": 10,
"unfilteredTotalItems": 196,
"unfilteredTotalPages": 20
}
},
"marketVersion": {
"type": "object",
"properties": {
"currentVersion": {
"type": "string",
"nullable": true,
"format": "date-time"
},
"availableVersions": {
"type": "array",
"nullable": true,
"items": {
"type": "string",
"nullable": true,
"format": "date-time"
}
}
}
}
},
"required": ["pagination", "marketVersion"]
},
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"domain": {
"type": "string"
},
"size": {
"type": "object",
"nullable": true,
"properties": {
"value": {
"type": "string"
},
"sortValue": {
"type": "number"
}
},
"required": ["value", "sortValue"]
},
"revenue": {
"type": "object",
"nullable": true,
"properties": {
"value": {
"type": "string"
},
"sortValue": {
"type": "number"
}
},
"required": ["value", "sortValue"]
},
"logoURL": {
"type": "string",
"nullable": true
},
"name": {
"type": "string",
"nullable": true
},
"description": {
"type": "string",
"nullable": true
},
"foundedYear": {
"type": "number",
"nullable": true
},
"hqCity": {
"type": "string",
"nullable": true
},
"hqState": {
"type": "string",
"nullable": true
},
"hqCountry": {
"type": "string",
"nullable": true
},
"momentum": {
"type": "object",
"nullable": true,
"properties": {
"funding": {
"type": "number",
"nullable": true
},
"webTraffic": {
"type": "number",
"nullable": true
},
"mediaAnalysis": {
"type": "number",
"nullable": true
},
"newsSentiment": {
"type": "number",
"nullable": true
},
"revenueEstimates": {
"type": "number",
"nullable": true
}
}
},
"overallMomentum": {
"type": "number",
"nullable": true
},
"actualRevenue": {
"nullable": true
},
"shareholdersList": {
"type": "array",
"nullable": true,
"items": {
"nullable": true
}
},
"locations": {
"type": "number",
"nullable": true
},
"topics": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"properties": {
"topicId": {
"type": "string"
},
"name": {
"type": "string"
},
"score": {
"type": "number"
}
},
"required": ["topicId", "name", "score"]
}
},
"versionDate": {
"type": "string",
"nullable": true,
"format": "date-time"
},
"userTags": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"properties": {
"id": {
"type": "number"
},
"label": {
"type": "string",
"nullable": true
},
"hexColor": {
"type": "string",
"nullable": true
},
"companyId": {
"type": "string"
},
"parentTagId": {
"type": "number"
}
},
"required": ["id", "label", "hexColor", "companyId", "parentTagId"]
}
},
"isFavourite": {
"type": "boolean",
"nullable": true
},
"categories": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"properties": {
"id": {
"type": "number"
},
"name": {
"type": "string"
}
},
"required": ["id", "name"]
}
},
"isLocationVerified": {
"type": "boolean",
"nullable": true
},
"certifications": {
"type": "array",
"nullable": true,
"items": {
"type": "string"
}
},
"contactNumber": {
"type": "string",
"nullable": true
},
"contactEmail": {
"type": "string",
"nullable": true
},
"parentCompany": {
"type": "string",
"nullable": true
},
"subsidiaries": {
"type": "array",
"nullable": true,
"items": {
"type": "string"
}
},
"founders": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"type": {
"type": "string",
"nullable": true
},
"image": {
"type": "string",
"nullable": true
}
},
"required": ["name"]
}
},
"ceo": {
"type": "string",
"nullable": true
},
"ukCompaniesHouseIds": {
"type": "array",
"nullable": true,
"items": {
"type": "string"
}
},
"ukPersonsWithSignificantControl": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"properties": {
"id": {
"type": "number"
},
"name": {
"type": "string"
},
"ownership": {
"type": "array",
"nullable": true,
"items": {
"type": "string"
}
},
"type": {
"type": "string",
"nullable": true
},
"status": {
"type": "boolean",
"nullable": true
},
"companyId": {
"type": "string",
"nullable": true
},
"companiesHouseURL": {
"type": "string",
"nullable": true
}
},
"required": ["id", "name"]
}
}
},
"required": ["id", "domain"]
}
}
},
"required": ["metadata", "data"]
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"examples": {
"INVALID_INPUT": {
"value": {
"success": false,
"errorCode": "INVALID_INPUT",
"message": "Bad Request"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"403": {
"description": "Forbidden - You do not have access to this market",
"content": {
"application/json": {
"examples": {
"FORBIDDEN": {
"value": {
"success": false,
"errorCode": "FORBIDDEN",
"message": "Forbidden - You do not have access to this market"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"404": {
"description": "Not Found - Market companies not found",
"content": {
"application/json": {
"examples": {
"NOT_FOUND": {
"value": {
"success": false,
"errorCode": "NOT_FOUND",
"message": "Not Found - Market companies not found"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"examples": {
"INTERNAL_SERVER_ERROR": {
"value": {
"success": false,
"errorCode": "INTERNAL_SERVER_ERROR",
"message": "Internal Server Error"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
}
}
}
},
"/v2/markets/{marketId}/explorer/companies/filters": {
"get": {
"tags": ["Markets"],
"summary": "Get market explorer filters",
"description": "Fetches available filters for a specific market.\n \n [List Market Explorer Companies](./list-market-explorer-companies) supports in its\n Query parameters a set of filters that can be applied to the list of companies. This\n endpoint provides the available options for those filters, which can be used to\n construct the query for listing companies. In particular, these filters are extracted\n across all companies in the market without pagination, allowing UI applications to\n show all available filters regardless of the pagination applied on the UI.\n \n Not typically useful for pure API consumers.",
"parameters": [
{
"schema": {
"type": "integer",
"minimum": 0,
"exclusiveMinimum": true,
"description": "ID of the market whose explorer companies will be retrieved."
},
"required": true,
"description": "ID of the market whose explorer companies will be retrieved.",
"name": "marketId",
"in": "path"
},
{
"schema": {
"type": "integer",
"minimum": 0,
"exclusiveMinimum": true,
"description": "Unique identifier for the team used to access the market, for determining access rights and blacklists.\n Team ID can be provided either in path or query parameter for backward compatibility; exactly one is required."
},
"required": false,
"description": "Unique identifier for the team used to access the market, for determining access rights and blacklists.\n Team ID can be provided either in path or query parameter for backward compatibility; exactly one is required.",
"name": "teamId",
"in": "path"
},
{
"schema": {
"type": "integer",
"minimum": 0,
"exclusiveMinimum": true,
"description": "Unique identifier for the team used to access the market, for determining access rights and blacklists.\n Team ID can be provided either in path or query parameter for backward compatibility; exactly one is required."
},
"required": false,
"description": "Unique identifier for the team used to access the market, for determining access rights and blacklists.\n Team ID can be provided either in path or query parameter for backward compatibility; exactly one is required.",
"name": "teamId",
"in": "query"
},
{
"schema": {
"type": "string",
"description": "Search term to filter companies by name, or description."
},
"required": false,
"description": "Search term to filter companies by name, or description.",
"name": "search",
"in": "query"
},
{
"schema": {
"type": "array",
"items": {
"type": "string"
}
},
"required": false,
"name": "domains",
"in": "query"
},
{
"schema": {
"type": "array",
"items": {
"type": "string"
}
},
"required": false,
"name": "categories",
"in": "query"
},
{
"schema": {
"type": "array",
"items": {
"type": "string"
}
},
"required": false,
"name": "userTags",
"in": "query"
},
{
"schema": {
"type": "boolean",
"nullable": true
},
"required": false,
"name": "favourites",
"in": "query"
},
{
"schema": {
"type": "array",
"items": {
"type": "string"
}
},
"required": false,
"name": "topics",
"in": "query"
},
{
"schema": {
"type": "array",
"items": {
"type": "string"
},
"description": "Filter by feature architecture node IDs. Prefix with 'e:' to exclude (e.g., '1, 2, e:3')."
},
"required": false,
"description": "Filter by feature architecture node IDs. Prefix with 'e:' to exclude (e.g., '1, 2, e:3').",
"name": "features",
"in": "query"
},
{
"schema": {
"type": "array",
"items": {
"type": "string"
}
},
"required": false,
"name": "size",
"in": "query"
},
{
"schema": {
"type": "array",
"items": {
"type": "string"
}
},
"required": false,
"name": "revenueRange",
"in": "query"
},
{
"schema": {
"type": "boolean",
"nullable": true
},
"required": false,
"name": "isLocationVerified",
"in": "query"
},
{
"schema": {
"type": "array",
"items": {
"type": "string"
}
},
"required": false,
"name": "hqCountry",
"in": "query"
},
{
"schema": {
"type": "array",
"items": {
"type": "string"
}
},
"required": false,
"name": "hqState",
"in": "query"
},
{
"schema": {
"type": "array",
"items": {
"type": "string"
}
},
"required": false,
"name": "hqCity",
"in": "query"
},
{
"schema": {
"type": "array",
"items": {
"type": "string"
}
},
"required": false,
"name": "phrases",
"in": "query"
},
{
"schema": {
"type": "object",
"properties": {
"min": {
"type": "integer",
"minimum": 0,
"maximum": 100
},
"max": {
"type": "integer",
"minimum": 0,
"maximum": 100
}
},
"required": ["min", "max"]
},
"required": false,
"name": "momentumScoreRange",
"in": "query"
},
{
"schema": {
"type": "object",
"properties": {
"min": {
"type": "integer",
"minimum": 1700,
"maximum": 2026
},
"max": {
"type": "integer",
"minimum": 1700,
"maximum": 2026
}
},
"required": ["min", "max"]
},
"required": false,
"name": "foundedYearRange",
"in": "query"
},
{
"schema": {
"type": "string",
"description": "Filter companies by version date."
},
"required": false,
"description": "Filter companies by version date.",
"name": "versionDate",
"in": "query"
}
],
"responses": {
"200": {
"description": "Market explorer filters response schema",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"yearFounded": {
"type": "object",
"properties": {
"filtered": {
"type": "array",
"items": {
"type": "object",
"properties": {
"label": {
"type": "string"
},
"count": {
"type": "number"
}
},
"required": ["label", "count"]
}
},
"unfiltered": {
"type": "array",
"items": {
"type": "object",
"properties": {
"label": {
"type": "string"
},
"count": {
"type": "number"
}
},
"required": ["label", "count"]
}
}
},
"required": ["filtered", "unfiltered"]
},
"yearFoundedMin": {
"type": "object",
"properties": {
"filtered": {
"type": "object",
"properties": {
"label": {
"type": "string"
},
"count": {
"type": "number"
}
},
"required": ["label", "count"]
},
"unfiltered": {
"type": "object",
"properties": {
"label": {
"type": "string"
},
"count": {
"type": "number"
}
},
"required": ["label", "count"]
}
},
"required": ["filtered", "unfiltered"]
},
"yearFoundedMax": {
"type": "object",
"properties": {
"filtered": {
"type": "object",
"properties": {
"label": {
"type": "string"
},
"count": {
"type": "number"
}
},
"required": ["label", "count"]
},
"unfiltered": {
"type": "object",
"properties": {
"label": {
"type": "string"
},
"count": {
"type": "number"
}
},
"required": ["label", "count"]
}
},
"required": ["filtered", "unfiltered"]
},
"companySize": {
"type": "object",
"properties": {
"filtered": {
"type": "array",
"items": {
"type": "object",
"properties": {
"label": {
"type": "string"
},
"count": {
"type": "number"
}
},
"required": ["label", "count"]
}
},
"unfiltered": {
"type": "array",
"items": {
"type": "object",
"properties": {
"label": {
"type": "string"
},
"count": {
"type": "number"
}
},
"required": ["label", "count"]
}
}
},
"required": ["filtered", "unfiltered"]
},
"companyRevenue": {
"type": "object",
"properties": {
"filtered": {
"type": "array",
"items": {
"type": "object",
"properties": {
"label": {
"type": "string"
},
"count": {
"type": "number"
}
},
"required": ["label", "count"]
}
},
"unfiltered": {
"type": "array",
"items": {
"type": "object",
"properties": {
"label": {
"type": "string"
},
"count": {
"type": "number"
}
},
"required": ["label", "count"]
}
}
},
"required": ["filtered", "unfiltered"]
},
"hqCountry": {
"type": "object",
"properties": {
"filtered": {
"type": "array",
"items": {
"type": "object",
"properties": {
"label": {
"type": "string"
},
"count": {
"type": "number"
}
},
"required": ["label", "count"]
}
},
"unfiltered": {
"type": "array",
"items": {
"type": "object",
"properties": {
"label": {
"type": "string"
},
"count": {
"type": "number"
}
},
"required": ["label", "count"]
}
}
},
"required": ["filtered", "unfiltered"]
},
"hqState": {
"type": "object",
"properties": {
"filtered": {
"type": "array",
"items": {
"type": "object",
"properties": {
"label": {
"type": "string"
},
"count": {
"type": "number"
}
},
"required": ["label", "count"]
}
},
"unfiltered": {
"type": "array",
"items": {
"type": "object",
"properties": {
"label": {
"type": "string"
},
"count": {
"type": "number"
}
},
"required": ["label", "count"]
}
}
},
"required": ["filtered", "unfiltered"]
},
"hqCity": {
"type": "object",
"properties": {
"filtered": {
"type": "array",
"items": {
"type": "object",
"properties": {
"label": {
"type": "string"
},
"count": {
"type": "number"
}
},
"required": ["label", "count"]
}
},
"unfiltered": {
"type": "array",
"items": {
"type": "object",
"properties": {
"label": {
"type": "string"
},
"count": {
"type": "number"
}
},
"required": ["label", "count"]
}
}
},
"required": ["filtered", "unfiltered"]
},
"categories": {
"type": "object",
"properties": {
"filtered": {
"type": "array",
"items": {
"type": "object",
"properties": {
"label": {
"type": "string"
},
"count": {
"type": "number"
}
},
"required": ["label", "count"]
}
},
"unfiltered": {
"type": "array",
"items": {
"type": "object",
"properties": {
"label": {
"type": "string"
},
"count": {
"type": "number"
}
},
"required": ["label", "count"]
}
}
},
"required": ["filtered", "unfiltered"]
},
"userTags": {
"type": "object",
"properties": {
"filtered": {
"type": "array",
"items": {
"type": "object",
"properties": {
"label": {
"type": "string"
},
"count": {
"type": "number"
}
},
"required": ["label", "count"]
}
},
"unfiltered": {
"type": "array",
"items": {
"type": "object",
"properties": {
"label": {
"type": "string"
},
"count": {
"type": "number"
}
},
"required": ["label", "count"]
}
}
},
"required": ["filtered", "unfiltered"]
},
"momentumScore": {
"type": "object",
"properties": {
"filtered": {
"type": "array",
"items": {
"type": "object",
"properties": {
"label": {
"type": "string"
},
"count": {
"type": "number"
}
},
"required": ["label", "count"]
}
},
"unfiltered": {
"type": "array",
"items": {
"type": "object",
"properties": {
"label": {
"type": "string"
},
"count": {
"type": "number"
}
},
"required": ["label", "count"]
}
}
},
"required": ["filtered", "unfiltered"]
},
"momentumScoreMin": {
"type": "object",
"properties": {
"filtered": {
"type": "object",
"properties": {
"label": {
"type": "string"
},
"count": {
"type": "number"
}
},
"required": ["label", "count"]
},
"unfiltered": {
"type": "object",
"properties": {
"label": {
"type": "string"
},
"count": {
"type": "number"
}
},
"required": ["label", "count"]
}
},
"required": ["filtered", "unfiltered"]
},
"momentumScoreMax": {
"type": "object",
"properties": {
"filtered": {
"type": "object",
"properties": {
"label": {
"type": "string"
},
"count": {
"type": "number"
}
},
"required": ["label", "count"]
},
"unfiltered": {
"type": "object",
"properties": {
"label": {
"type": "string"
},
"count": {
"type": "number"
}
},
"required": ["label", "count"]
}
},
"required": ["filtered", "unfiltered"]
},
"isLocationVerified": {
"type": "object",
"properties": {
"filtered": {
"type": "object",
"properties": {
"label": {
"type": "string"
},
"count": {
"type": "number"
}
},
"required": ["label", "count"]
},
"unfiltered": {
"type": "object",
"properties": {
"label": {
"type": "string"
},
"count": {
"type": "number"
}
},
"required": ["label", "count"]
}
},
"required": ["filtered", "unfiltered"]
}
},
"required": [
"yearFounded",
"yearFoundedMin",
"yearFoundedMax",
"companySize",
"companyRevenue",
"hqCountry",
"hqState",
"hqCity",
"categories",
"userTags",
"momentumScore",
"momentumScoreMin",
"momentumScoreMax",
"isLocationVerified"
]
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"examples": {
"INVALID_INPUT": {
"value": {
"success": false,
"errorCode": "INVALID_INPUT",
"message": "Bad Request"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"403": {
"description": "Forbidden - You do not have access to this market",
"content": {
"application/json": {
"examples": {
"FORBIDDEN": {
"value": {
"success": false,
"errorCode": "FORBIDDEN",
"message": "Forbidden - You do not have access to this market"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"examples": {
"INTERNAL_SERVER_ERROR": {
"value": {
"success": false,
"errorCode": "INTERNAL_SERVER_ERROR",
"message": "Internal Server Error"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
}
}
}
},
"/v2/markets/exportViaAPI/{teamId}/{studyId}": {
"post": {
"tags": ["Markets"],
"summary": "Export market data to customer endpoint",
"description": "Export market data to a configured customer endpoint using the team's registered API endpoints.",
"parameters": [
{
"schema": {
"type": "integer",
"minimum": 1
},
"required": true,
"name": "teamId",
"in": "path"
},
{
"schema": {
"type": "integer",
"minimum": 1
},
"required": true,
"name": "studyId",
"in": "path"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"endpointName": {
"type": "string",
"minLength": 4
},
"domains": {
"type": "array",
"items": {
"type": "string"
},
"description": "Optional array of domain strings to export. If not provided, all domains for the study will be exported."
}
},
"required": ["endpointName"]
}
}
}
},
"responses": {
"200": {
"description": "Successful export to customer API.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string"
},
"message": {
"type": "string"
},
"redirectUrl": {
"type": "string",
"nullable": true
}
},
"required": ["title", "message"]
}
}
}
},
"204": {
"description": "No companies associated with study - nothing to export.",
"content": {
"application/json": {
"schema": {}
}
}
},
"400": {
"description": "Customer returned 4xx or 207 with a valid error payload.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string"
},
"message": {
"type": "string"
},
"references": {
"type": "array",
"items": {
"type": "object",
"properties": {
"title": {
"type": "string"
},
"message": {
"type": "string"
},
"url": {
"type": "string",
"format": "uri"
},
"type": {
"type": "string",
"enum": ["ok", "info", "warning", "error"]
}
},
"required": ["title"]
}
}
},
"required": ["title", "message"]
}
}
}
},
"502": {
"description": "Customer returned 4xx/207 but response shape invalid (shown as endpoint error).",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"title": {
"type": "string"
},
"message": {
"type": "string"
},
"references": {
"type": "array",
"items": {
"type": "object",
"properties": {
"title": {
"type": "string"
},
"message": {
"type": "string"
},
"url": {
"type": "string",
"format": "uri"
},
"type": {
"type": "string",
"enum": ["ok", "info", "warning", "error"]
}
},
"required": ["title"]
}
}
},
"required": ["title", "message"]
}
}
}
}
}
}
},
"/v2/markets/{marketId}/jobs": {
"put": {
"tags": ["Markets"],
"summary": "Create a job for a market",
"description": "Ergonomic alias for PUT /v2/jobs/study-{marketId}. Creates a job record in DynamoDB under the study-{marketId} origin. Use this before triggering the ETL pipeline — the record must exist so the frontend can poll immediately and display a queued state during pipeline start-up. Valid workflowName values for markets: discovery-platform and publish-platform groups.",
"parameters": [
{
"schema": {
"type": "integer",
"minimum": 0,
"exclusiveMinimum": true,
"description": "Unique identifier of the market (study)."
},
"required": true,
"description": "Unique identifier of the market (study).",
"name": "marketId",
"in": "path"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"workflowName": {
"type": "string",
"enum": [
"python-first-pass",
"python-second-pass",
"python-first-pass-v3-manual-add-domains",
"python-location-discovery",
"publish-study",
"python-scrape",
"python-web-traffic",
"python-momentum-scoring",
"python-competitors",
"python-news",
"python-news-article-scrape",
"python-search-esg",
"python-embed-scrapes",
"python-extract-phrases",
"python-topic-analysis",
"python-generate-feature-map",
"mongo-publish-study",
"mongo-python-web-traffic",
"mongo-python-competitors",
"mongo-python-momentum-scoring",
"mongo-python-news",
"mongo-python-news-article-scrape",
"mongo-python-search-esg",
"mongo-python-topic-analysis",
"initial",
"daily-update",
"weekly-update",
"monthly-update",
"biannual-update",
"manual-update",
"forced-update",
"auto-update"
],
"description": "The workflow to run. Must be valid for the origin type (study vs agent)."
},
"teamId": {
"type": "integer",
"minimum": 0,
"exclusiveMinimum": true,
"description": "Team ID for access control."
}
},
"required": ["workflowName", "teamId"]
}
}
}
},
"responses": {
"201": {
"description": "Job created. Trigger the ETL pipeline with the returned jobId and jobOrigin.",
"content": {
"application/json": {
"examples": {
"study-queued": {
"summary": "Discovery job created for a market",
"value": {
"jobId": "discovery-platform::python-first-pass::2026-01-07T11:26:50.406Z::04cda5",
"jobOrigin": "study-1234",
"workflowGroup": "discovery-platform",
"workflowName": "python-first-pass",
"status": "queued",
"progress": 0,
"startTime": "2026-01-07T11:26:50.406Z",
"endTime": null
}
},
"agent-queued": {
"summary": "Agent initial job created",
"value": {
"jobId": "agent-initial::initial::2026-03-01T09:00:00.000Z::f1e2d3",
"jobOrigin": "agent-abc123",
"workflowGroup": "agent-initial",
"workflowName": "initial",
"status": "queued",
"progress": 0,
"startTime": "2026-03-01T09:00:00.000Z",
"endTime": null
}
}
},
"schema": {
"type": "object",
"properties": {
"jobId": {
"type": "string",
"description": "Composite job identifier in the format \"::::::\". This is also the DynamoDB sort key on the job-metadata table."
},
"jobOrigin": {
"type": "string",
"description": "DynamoDB partition key identifying the resource that owns this job. Format: \"-\", e.g. \"study-1234\" or \"agent-abc123\"."
},
"workflowGroup": {
"type": "string",
"description": "The workflow group this job belongs to (e.g. 'discovery-platform')."
},
"workflowName": {
"type": "string",
"description": "The specific workflow this job ran (e.g. 'python-first-pass')."
},
"status": {
"type": "string",
"enum": ["queued", "running", "completed", "stuck", "failed"],
"description": "Derived job status. 'failed' = taskComplete=true with no finishedAt (Python encoding). 'stuck' = not complete and started >1h ago."
},
"progress": {
"type": "number",
"minimum": 0,
"maximum": 100,
"description": "Progress percentage 0–100."
},
"startTime": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 UTC timestamp of job start."
},
"endTime": {
"type": "string",
"nullable": true,
"format": "date-time",
"description": "ISO 8601 UTC timestamp of job completion, or null if running."
}
},
"required": [
"jobId",
"jobOrigin",
"workflowGroup",
"workflowName",
"status",
"progress",
"startTime",
"endTime"
]
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"examples": {
"INVALID_INPUT": {
"value": {
"success": false,
"errorCode": "INVALID_INPUT",
"message": "Bad Request"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"examples": {
"FORBIDDEN": {
"value": {
"success": false,
"errorCode": "FORBIDDEN",
"message": "Forbidden"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"examples": {
"INTERNAL_SERVER_ERROR": {
"value": {
"success": false,
"errorCode": "INTERNAL_SERVER_ERROR",
"message": "Internal Server Error"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
}
}
},
"get": {
"tags": ["Markets"],
"summary": "Get job status for a market",
"description": "Ergonomic alias for GET /v2/jobs/study-{marketId}. Accepts the same query parameters (workflowGroup, workflowName, status, jobIds, latest). Prefer this endpoint when working with markets; use GET /v2/jobs/{jobOrigin} directly when you already have a jobOrigin string.",
"parameters": [
{
"schema": {
"type": "integer",
"minimum": 0,
"exclusiveMinimum": true,
"description": "Unique identifier of the market (study)."
},
"required": true,
"description": "Unique identifier of the market (study).",
"name": "marketId",
"in": "path"
},
{
"schema": {
"type": "integer",
"minimum": 0,
"exclusiveMinimum": true,
"description": "Team ID for access control."
},
"required": true,
"description": "Team ID for access control.",
"name": "teamId",
"in": "query"
},
{
"schema": {
"type": "string",
"enum": ["discovery-platform", "publish-platform", "publish-mongo", "agent-initial", "agent-update"],
"description": "Filter to jobs in this workflow group. Required when using latest=true."
},
"required": false,
"description": "Filter to jobs in this workflow group. Required when using latest=true.",
"name": "workflowGroup",
"in": "query"
},
{
"schema": {
"type": "string",
"enum": [
"python-first-pass",
"python-second-pass",
"python-first-pass-v3-manual-add-domains",
"python-location-discovery",
"publish-study",
"python-scrape",
"python-web-traffic",
"python-momentum-scoring",
"python-competitors",
"python-news",
"python-news-article-scrape",
"python-search-esg",
"python-embed-scrapes",
"python-extract-phrases",
"python-topic-analysis",
"python-generate-feature-map",
"mongo-publish-study",
"mongo-python-web-traffic",
"mongo-python-competitors",
"mongo-python-momentum-scoring",
"mongo-python-news",
"mongo-python-news-article-scrape",
"mongo-python-search-esg",
"mongo-python-topic-analysis",
"initial",
"daily-update",
"weekly-update",
"monthly-update",
"biannual-update",
"manual-update",
"forced-update",
"auto-update"
],
"description": "Filter to jobs with this exact workflow name. Cannot be combined with workflowGroup."
},
"required": false,
"description": "Filter to jobs with this exact workflow name. Cannot be combined with workflowGroup.",
"name": "workflowName",
"in": "query"
},
{
"schema": {
"anyOf": [
{
"type": "string",
"enum": ["queued", "running", "completed", "stuck", "failed"]
},
{
"type": "array",
"items": {
"type": "string",
"enum": ["queued", "running", "completed", "stuck", "failed"]
}
}
],
"description": "Filter by job status. Can be repeated: ?status=running&status=stuck"
},
"required": false,
"description": "Filter by job status. Can be repeated: ?status=running&status=stuck",
"name": "status",
"in": "query"
},
{
"schema": {
"anyOf": [
{
"type": "string"
},
{
"type": "array",
"items": {
"type": "string"
}
}
],
"description": "Fetch specific job IDs via DynamoDB BatchGet. Can be repeated: ?jobIds=abc&jobIds=def"
},
"required": false,
"description": "Fetch specific job IDs via DynamoDB BatchGet. Can be repeated: ?jobIds=abc&jobIds=def",
"name": "jobIds",
"in": "query"
},
{
"schema": {
"type": "boolean",
"nullable": true,
"default": false,
"description": "When true, return only the most recent job per workflow in the group. Requires workflowGroup."
},
"required": false,
"description": "When true, return only the most recent job per workflow in the group. Requires workflowGroup.",
"name": "latest",
"in": "query"
}
],
"responses": {
"200": {
"description": "Job statuses retrieved successfully.",
"content": {
"application/json": {
"examples": {
"study-running": {
"summary": "Study jobs in progress",
"value": {
"metadata": {
"jobOrigin": "study-1234"
},
"data": [
{
"jobId": "discovery-platform::python-first-pass::2026-01-07T11:26:50.406Z::04cda5",
"jobOrigin": "study-1234",
"workflowGroup": "discovery-platform",
"workflowName": "python-first-pass",
"status": "running",
"progress": 65,
"startTime": "2026-01-07T11:26:50.406Z",
"endTime": null
}
]
}
},
"agent-completed": {
"summary": "Agent jobs completed",
"value": {
"metadata": {
"jobOrigin": "agent-abc123"
},
"data": [
{
"jobId": "agent-initial::initial::2026-03-01T09:00:00.000Z::f1e2d3",
"jobOrigin": "agent-abc123",
"workflowGroup": "agent-initial",
"workflowName": "initial",
"status": "completed",
"progress": 100,
"startTime": "2026-03-01T09:00:00.000Z",
"endTime": "2026-03-01T09:45:00.000Z"
}
]
}
}
},
"schema": {
"type": "object",
"properties": {
"metadata": {
"type": "object",
"properties": {
"jobOrigin": {
"type": "string",
"description": "DynamoDB partition key identifying the resource that owns this job. Format: \"-\", e.g. \"study-1234\" or \"agent-abc123\"."
}
},
"required": ["jobOrigin"]
},
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"jobId": {
"type": "string",
"description": "Composite job identifier in the format \"::::::\". This is also the DynamoDB sort key on the job-metadata table."
},
"jobOrigin": {
"type": "string",
"description": "DynamoDB partition key identifying the resource that owns this job. Format: \"-\", e.g. \"study-1234\" or \"agent-abc123\"."
},
"workflowGroup": {
"type": "string",
"description": "The workflow group this job belongs to (e.g. 'discovery-platform')."
},
"workflowName": {
"type": "string",
"description": "The specific workflow this job ran (e.g. 'python-first-pass')."
},
"status": {
"type": "string",
"enum": ["queued", "running", "completed", "stuck", "failed"],
"description": "Derived job status. 'failed' = taskComplete=true with no finishedAt (Python encoding). 'stuck' = not complete and started >1h ago."
},
"progress": {
"type": "number",
"minimum": 0,
"maximum": 100,
"description": "Progress percentage 0–100."
},
"startTime": {
"type": "string",
"format": "date-time",
"description": "ISO 8601 UTC timestamp of job start."
},
"endTime": {
"type": "string",
"nullable": true,
"format": "date-time",
"description": "ISO 8601 UTC timestamp of job completion, or null if running."
}
},
"required": [
"jobId",
"jobOrigin",
"workflowGroup",
"workflowName",
"status",
"progress",
"startTime",
"endTime"
]
}
}
},
"required": ["metadata", "data"]
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"examples": {
"INVALID_INPUT": {
"value": {
"success": false,
"errorCode": "INVALID_INPUT",
"message": "Bad Request"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"examples": {
"FORBIDDEN": {
"value": {
"success": false,
"errorCode": "FORBIDDEN",
"message": "Forbidden"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"examples": {
"INTERNAL_SERVER_ERROR": {
"value": {
"success": false,
"errorCode": "INTERNAL_SERVER_ERROR",
"message": "Internal Server Error"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
}
}
}
},
"/v2/markets/{marketId}/jobs/messages": {
"get": {
"tags": ["Markets"],
"summary": "Get job messages for a market",
"description": "Ergonomic alias for GET /v2/jobs/study-{marketId}/messages. Supports lastSeenDate incremental polling. Prefer this endpoint when working with markets.",
"parameters": [
{
"schema": {
"type": "integer",
"minimum": 0,
"exclusiveMinimum": true,
"description": "Unique identifier of the market (study)."
},
"required": true,
"description": "Unique identifier of the market (study).",
"name": "marketId",
"in": "path"
},
{
"schema": {
"type": "integer",
"minimum": 0,
"exclusiveMinimum": true,
"description": "Team ID for access control."
},
"required": true,
"description": "Team ID for access control.",
"name": "teamId",
"in": "query"
},
{
"schema": {
"type": "string",
"format": "date-time",
"description": "Return only messages with a timestamp at or after this date. Naive datetimes are treated as UTC; offset-aware datetimes are converted to UTC. Omit to receive the full history (until TTL expiry). Example: 2026-01-07T11:00:00.000Z"
},
"required": false,
"description": "Return only messages with a timestamp at or after this date. Naive datetimes are treated as UTC; offset-aware datetimes are converted to UTC. Omit to receive the full history (until TTL expiry). Example: 2026-01-07T11:00:00.000Z",
"name": "lastSeenDate",
"in": "query"
},
{
"schema": {
"type": "string",
"minLength": 1,
"description": "Filter messages to a specific job ID. Omit to receive messages for all jobs at this origin."
},
"required": false,
"description": "Filter messages to a specific job ID. Omit to receive messages for all jobs at this origin.",
"name": "jobId",
"in": "query"
}
],
"responses": {
"200": {
"description": "Messages retrieved successfully.",
"content": {
"application/json": {
"examples": {
"incremental-poll": {
"summary": "Incremental poll — new messages since lastSeenDate",
"value": {
"metadata": {
"jobOrigin": "study-1234"
},
"data": [
{
"jobOrigin": "study-1234",
"timestamp": "2026-01-07T11:30:00.000Z::a1b2c3",
"jobId": "discovery-platform::python-first-pass::2026-01-07T11:26:50.406Z::04cda5",
"type": "step",
"message": "Processing batch 3 of 10"
},
{
"jobOrigin": "study-1234",
"timestamp": "2026-01-07T11:31:05.000Z::d4e5f6",
"jobId": "discovery-platform::python-first-pass::2026-01-07T11:26:50.406Z::04cda5",
"type": "content",
"message": "Found 12 additional candidates",
"data": {
"count": 12
}
}
]
}
}
},
"schema": {
"type": "object",
"properties": {
"metadata": {
"type": "object",
"properties": {
"jobOrigin": {
"type": "string",
"description": "DynamoDB partition key identifying the resource that owns this job. Format: \"-\", e.g. \"study-1234\" or \"agent-abc123\"."
}
},
"required": ["jobOrigin"]
},
"data": {
"type": "array",
"items": {
"oneOf": [
{
"type": "object",
"properties": {
"jobOrigin": {
"type": "string",
"description": "DynamoDB partition key identifying the resource that owns this job. Format: \"-\", e.g. \"study-1234\" or \"agent-abc123\"."
},
"timestamp": {
"type": "string",
"description": "DynamoDB sort key in the format '::'. Guaranteed chronologically sortable."
},
"jobId": {
"type": "string",
"description": "Composite job identifier in the format \"::::::\". This is also the DynamoDB sort key on the job-metadata table."
},
"type": {
"type": "string",
"enum": ["step"]
},
"data": {
"type": "object",
"properties": {
"step": {
"type": "string",
"minLength": 1,
"description": "Step name or identifier."
},
"status": {
"type": "string",
"enum": ["pending", "running", "completed", "failed", "skipped"],
"description": "Current status of the step."
},
"progress": {
"type": "number",
"nullable": true,
"minimum": 0,
"maximum": 1,
"description": "Progress within this step (0.0–1.0)."
},
"result": {
"type": "string",
"nullable": true,
"description": "Human-readable result summary."
},
"parentStep": {
"type": "string",
"nullable": true,
"description": "Parent step name for nested steps."
},
"metadata": {
"type": "object",
"nullable": true,
"additionalProperties": {
"nullable": true
},
"description": "Optional metadata dictionary for additional context."
}
},
"required": ["step", "status"],
"additionalProperties": {
"nullable": true
}
}
},
"required": ["jobOrigin", "timestamp", "type", "data"]
},
{
"type": "object",
"properties": {
"jobOrigin": {
"type": "string",
"description": "DynamoDB partition key identifying the resource that owns this job. Format: \"-\", e.g. \"study-1234\" or \"agent-abc123\"."
},
"timestamp": {
"type": "string",
"description": "DynamoDB sort key in the format '::'. Guaranteed chronologically sortable."
},
"jobId": {
"type": "string",
"description": "Composite job identifier in the format \"::::::\". This is also the DynamoDB sort key on the job-metadata table."
},
"type": {
"type": "string",
"enum": ["content"]
},
"data": {
"type": "object",
"properties": {
"content": {
"type": "string",
"nullable": true,
"description": "Text or markdown content body."
},
"contentType": {
"type": "string",
"nullable": true,
"description": "MIME type (e.g. 'text/plain', 'text/html')."
},
"sourceUrl": {
"type": "string",
"nullable": true,
"description": "URL or path where content originated."
},
"metadata": {
"type": "object",
"nullable": true,
"additionalProperties": {
"nullable": true
},
"description": "Optional metadata dictionary for additional context."
}
},
"additionalProperties": {
"nullable": true
}
}
},
"required": ["jobOrigin", "timestamp", "type", "data"]
},
{
"type": "object",
"properties": {
"jobOrigin": {
"type": "string",
"description": "DynamoDB partition key identifying the resource that owns this job. Format: \"-\", e.g. \"study-1234\" or \"agent-abc123\"."
},
"timestamp": {
"type": "string",
"description": "DynamoDB sort key in the format '::'. Guaranteed chronologically sortable."
},
"jobId": {
"type": "string",
"description": "Composite job identifier in the format \"::::::\". This is also the DynamoDB sort key on the job-metadata table."
},
"type": {
"type": "string",
"enum": ["search_results"]
},
"data": {
"type": "object",
"properties": {
"query": {
"type": "string",
"nullable": true,
"description": "Search query or filter criteria."
},
"totalResults": {
"type": "integer",
"nullable": true,
"minimum": 0,
"description": "Total number of results found."
},
"resultsReturned": {
"type": "integer",
"nullable": true,
"minimum": 0,
"description": "Number of results included in this message."
},
"page": {
"type": "integer",
"nullable": true,
"minimum": 1,
"description": "Page number for paginated results."
},
"source": {
"type": "string",
"nullable": true,
"description": "Source identifier (e.g. 'google', 'bing', 'internal')."
},
"results": {
"type": "array",
"nullable": true,
"items": {
"type": "object",
"additionalProperties": {
"nullable": true
}
},
"description": "Structured result data."
},
"metadata": {
"type": "object",
"nullable": true,
"additionalProperties": {
"nullable": true
},
"description": "Optional metadata dictionary for additional context."
}
},
"additionalProperties": {
"nullable": true
}
}
},
"required": ["jobOrigin", "timestamp", "type", "data"]
},
{
"type": "object",
"properties": {
"jobOrigin": {
"type": "string",
"description": "DynamoDB partition key identifying the resource that owns this job. Format: \"-\", e.g. \"study-1234\" or \"agent-abc123\"."
},
"timestamp": {
"type": "string",
"description": "DynamoDB sort key in the format '::'. Guaranteed chronologically sortable."
},
"jobId": {
"type": "string",
"description": "Composite job identifier in the format \"::::::\". This is also the DynamoDB sort key on the job-metadata table."
},
"type": {
"type": "string",
"enum": ["image"]
},
"data": {
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "URL or S3 path to the image."
},
"mimeType": {
"type": "string",
"description": "MIME type (e.g. 'image/png', 'image/jpeg')."
},
"width": {
"type": "integer",
"nullable": true,
"minimum": 0,
"exclusiveMinimum": true,
"description": "Image width in pixels."
},
"height": {
"type": "integer",
"nullable": true,
"minimum": 0,
"exclusiveMinimum": true,
"description": "Image height in pixels."
},
"sizeBytes": {
"type": "integer",
"nullable": true,
"minimum": 0,
"description": "File size in bytes."
},
"altText": {
"type": "string",
"nullable": true,
"description": "Alternative text description."
},
"thumbnailUrl": {
"type": "string",
"nullable": true,
"description": "URL to thumbnail version of the image."
},
"metadata": {
"type": "object",
"nullable": true,
"additionalProperties": {
"nullable": true
},
"description": "Optional metadata dictionary for additional context."
}
},
"additionalProperties": {
"nullable": true
}
}
},
"required": ["jobOrigin", "timestamp", "type", "data"]
},
{
"type": "object",
"properties": {
"jobOrigin": {
"type": "string",
"description": "DynamoDB partition key identifying the resource that owns this job. Format: \"-\", e.g. \"study-1234\" or \"agent-abc123\"."
},
"timestamp": {
"type": "string",
"description": "DynamoDB sort key in the format '::'. Guaranteed chronologically sortable."
},
"jobId": {
"type": "string",
"description": "Composite job identifier in the format \"::::::\". This is also the DynamoDB sort key on the job-metadata table."
},
"type": {
"type": "string",
"enum": ["warn"]
},
"data": {
"type": "object",
"properties": {
"warningCode": {
"type": "string",
"nullable": true,
"description": "Warning code or identifier."
},
"warningMessage": {
"type": "string",
"nullable": true,
"description": "Human-readable warning message."
},
"recoverable": {
"type": "boolean",
"nullable": true,
"description": "Whether the issue is recoverable."
},
"retryCount": {
"type": "integer",
"nullable": true,
"minimum": 0,
"description": "Number of retries attempted."
},
"context": {
"type": "object",
"nullable": true,
"additionalProperties": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"nullable": true
}
]
},
"description": "Contextual data (e.g. affected resource IDs)."
},
"metadata": {
"type": "object",
"nullable": true,
"additionalProperties": {
"nullable": true
},
"description": "Optional metadata dictionary for additional context."
}
},
"additionalProperties": {
"nullable": true
}
}
},
"required": ["jobOrigin", "timestamp", "type", "data"]
},
{
"type": "object",
"properties": {
"jobOrigin": {
"type": "string",
"description": "DynamoDB partition key identifying the resource that owns this job. Format: \"-\", e.g. \"study-1234\" or \"agent-abc123\"."
},
"timestamp": {
"type": "string",
"description": "DynamoDB sort key in the format '::'. Guaranteed chronologically sortable."
},
"jobId": {
"type": "string",
"description": "Composite job identifier in the format \"::::::\". This is also the DynamoDB sort key on the job-metadata table."
},
"type": {
"type": "string",
"enum": ["error"]
},
"data": {
"type": "object",
"properties": {
"errorCode": {
"type": "string",
"nullable": true,
"description": "Error code or identifier."
},
"errorMessage": {
"type": "string",
"nullable": true,
"description": "Human-readable error message."
},
"exceptionType": {
"type": "string",
"nullable": true,
"description": "Exception class name (e.g. 'ValueError', 'HTTPError')."
},
"stackTrace": {
"type": "string",
"nullable": true,
"description": "Stack trace (may be truncated or sanitised)."
},
"recoverable": {
"type": "boolean",
"nullable": true,
"description": "Whether the error is recoverable."
},
"context": {
"type": "object",
"nullable": true,
"additionalProperties": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"type": "boolean"
},
{
"nullable": true
}
]
},
"description": "Contextual data (e.g. input parameters, resource state)."
},
"metadata": {
"type": "object",
"nullable": true,
"additionalProperties": {
"nullable": true
},
"description": "Optional metadata dictionary for additional context."
}
},
"additionalProperties": {
"nullable": true
}
}
},
"required": ["jobOrigin", "timestamp", "type", "data"]
}
]
}
}
},
"required": ["metadata", "data"]
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"examples": {
"INVALID_INPUT": {
"value": {
"success": false,
"errorCode": "INVALID_INPUT",
"message": "Bad Request"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"examples": {
"FORBIDDEN": {
"value": {
"success": false,
"errorCode": "FORBIDDEN",
"message": "Forbidden"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"examples": {
"INTERNAL_SERVER_ERROR": {
"value": {
"success": false,
"errorCode": "INTERNAL_SERVER_ERROR",
"message": "Internal Server Error"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
}
}
}
},
"/v2/impact/search": {
"post": {
"tags": ["Impact"],
"summary": "Search companies",
"description": "Search for impact data",
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"searchType": {
"type": "string",
"enum": ["keywordSearch", "domainSearch"],
"description": "Type of search to perform: keyword-based or domain-based."
},
"keyword": {
"type": "string",
"minLength": 1,
"description": "Keyword or domain name to search for."
},
"location": {
"type": "string",
"description": "Optional location filter to refine search results."
},
"page": {
"type": "number",
"minimum": 1,
"maximum": 100,
"description": "Page number for paginated search results (1–100)."
},
"perPage": {
"type": "number",
"minimum": 10,
"maximum": 100,
"description": "Number of items per page (10–100)."
},
"filters": {
"type": "object",
"properties": {
"certifications": {
"type": "array",
"items": {
"type": "string"
},
"description": "List of certifications to filter companies by."
},
"naicsCodes": {
"type": "array",
"items": {
"type": "object",
"properties": {
"value": {
"type": "string",
"description": "NAICS code value."
},
"label": {
"type": "string",
"description": "Readable label for the NAICS code."
}
},
"required": ["value", "label"]
},
"description": "List of NAICS codes to filter companies by."
},
"companyKeyword": {
"type": "string",
"description": "Keyword to further filter company names or descriptions."
}
},
"description": "Optional filters applied to the search."
},
"sort": {
"type": "object",
"properties": {
"field": {
"type": "string",
"enum": ["name", "relevance"],
"description": "Field to sort by: company name or search relevance."
},
"direction": {
"type": "string",
"enum": ["asc", "desc"],
"description": "Sort direction: ascending or descending."
}
},
"description": "Optional sorting parameters."
}
},
"required": ["searchType", "keyword"]
}
}
}
},
"responses": {
"200": {
"description": "Search impact data response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"nameOfFirm": {
"type": "string",
"nullable": true,
"description": "Name of the firm."
},
"description": {
"type": "string",
"nullable": true,
"description": "Brief description of the firm."
},
"keywords": {
"type": "array",
"nullable": true,
"items": {
"type": "string"
},
"description": "List of keywords associated with the firm."
},
"certifications": {
"type": "array",
"nullable": true,
"items": {
"type": "string"
},
"description": "Verified certifications the firm holds."
},
"unverifiedCertifications": {
"type": "array",
"nullable": true,
"items": {
"type": "string"
},
"description": "Unverified certifications claimed by the firm."
},
"city": {
"type": "string",
"nullable": true,
"description": "City where the firm is located."
},
"domain": {
"type": "string",
"nullable": true,
"description": "Website domain of the firm."
},
"url": {
"type": "string",
"nullable": true,
"description": "URL link to the firm’s website."
},
"naicsCodes": {
"type": "array",
"nullable": true,
"items": {
"type": "number"
},
"description": "List of NAICS codes associated with the firm."
},
"naicsDescriptions": {
"type": "array",
"nullable": true,
"items": {
"type": "string"
},
"description": "Descriptions for the firm's NAICS codes."
},
"revenue": {
"type": "object",
"nullable": true,
"properties": {
"id": {
"type": "number",
"nullable": true,
"description": "Revenue bracket identifier."
},
"label": {
"type": "string",
"nullable": true,
"description": "Revenue range label."
},
"actual": {
"type": "object",
"properties": {
"value": {
"type": "number",
"nullable": true,
"description": "Actual revenue value."
},
"currency": {
"type": "string",
"nullable": true,
"description": "Currency of the revenue."
}
}
}
},
"required": ["actual"],
"description": "Revenue information for the firm."
},
"size": {
"type": "object",
"nullable": true,
"properties": {
"id": {
"type": "number",
"nullable": true,
"description": "Size bracket identifier."
},
"label": {
"type": "string",
"nullable": true,
"description": "Size range label."
},
"actual": {
"type": "number",
"nullable": true,
"description": "Actual size of the company."
}
},
"description": "Company size information."
},
"score": {
"type": "number",
"nullable": true,
"description": "Relevance score of the search result."
},
"revenueDelta": {
"type": "number",
"nullable": true,
"description": "Change in revenue compared to previous data."
},
"sizeDelta": {
"type": "number",
"nullable": true,
"description": "Change in company size compared to previous data."
},
"location": {
"type": "object",
"properties": {
"state": {
"type": "object",
"nullable": true,
"properties": {
"type": {
"type": "string",
"nullable": true,
"description": "Type of the state location."
},
"name": {
"type": "string",
"nullable": true,
"description": "State name."
},
"code": {
"type": "string",
"nullable": true,
"description": "State code abbreviation."
},
"country": {
"type": "string",
"nullable": true,
"description": "Country of the state."
}
}
},
"country": {
"type": "object",
"nullable": true,
"properties": {
"type": {
"type": "string",
"nullable": true,
"description": "Type of the country location."
},
"name": {
"type": "string",
"nullable": true,
"description": "Country name."
},
"code": {
"type": "string",
"nullable": true,
"description": "Country code abbreviation."
}
}
}
},
"description": "Location information for the firm."
}
},
"required": ["location"]
},
"description": "List of companies returned by the search."
},
"meta": {
"type": "object",
"properties": {
"totalItems": {
"type": "number",
"description": "Total number of search results."
},
"currentPage": {
"type": "number",
"description": "Current page number."
},
"totalPages": {
"type": "number",
"description": "Total number of pages available."
},
"itemsPerPage": {
"type": "number",
"description": "Number of items displayed per page."
}
},
"required": ["totalItems", "currentPage", "totalPages", "itemsPerPage"],
"description": "Pagination metadata for the search results."
}
},
"required": ["data", "meta"]
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"examples": {
"INVALID_INPUT": {
"value": {
"success": false,
"errorCode": "INVALID_INPUT",
"message": "Bad Request"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"403": {
"description": "Forbidden",
"content": {
"application/json": {
"examples": {
"FORBIDDEN": {
"value": {
"success": false,
"errorCode": "FORBIDDEN",
"message": "Forbidden"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"examples": {
"INTERNAL_SERVER_ERROR": {
"value": {
"success": false,
"errorCode": "INTERNAL_SERVER_ERROR",
"message": "Internal Server Error"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
}
}
}
},
"/v2/impact/companies/{identifier}": {
"get": {
"tags": ["Impact"],
"summary": "Get a company",
"description": "Get impact data for a specific company",
"parameters": [
{
"schema": {
"type": "string",
"minLength": 1,
"description": "Unique identifier of the company."
},
"required": true,
"description": "Unique identifier of the company.",
"name": "identifier",
"in": "path"
}
],
"responses": {
"200": {
"description": "Get impact data for a specific company response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"_id": {
"type": "string",
"nullable": true,
"description": "MongoDB ObjectId of the company."
},
"domain": {
"type": "string",
"nullable": true,
"description": "Company's domain name."
},
"nameOfFirm": {
"type": "string",
"nullable": true,
"description": "Name of the firm."
},
"addressLine1": {
"type": "string",
"nullable": true,
"description": "Primary address line."
},
"addressLine2": {
"type": "string",
"nullable": true,
"description": "Secondary address line."
},
"city": {
"type": "string",
"nullable": true,
"description": "City where the company is located."
},
"phoneNumber": {
"type": "string",
"nullable": true,
"description": "Primary phone number of the company."
},
"eMailAddress": {
"type": "string",
"nullable": true,
"description": "Primary email address of the company."
},
"yearEstablished": {
"type": "string",
"nullable": true,
"description": "Year the company was established."
},
"keywords": {
"type": "array",
"nullable": true,
"items": {
"type": "string"
},
"description": "Keywords associated with the company."
},
"naicsCodes": {
"type": "array",
"nullable": true,
"items": {
"type": "number"
},
"description": "List of NAICS codes for the company."
},
"naicsDescriptions": {
"type": "array",
"nullable": true,
"items": {
"type": "string"
},
"description": "Descriptions for the company's NAICS codes."
},
"description": {
"type": "string",
"nullable": true,
"description": "Brief description of the company."
},
"certifications": {
"type": "array",
"nullable": true,
"items": {
"type": "string"
},
"description": "Verified certifications held by the company."
},
"unverifiedCertifications": {
"type": "array",
"nullable": true,
"items": {
"type": "string"
},
"description": "Unverified certifications claimed by the company."
},
"revenue": {
"type": "object",
"nullable": true,
"properties": {
"id": {
"type": "number",
"nullable": true,
"description": "Revenue bracket identifier."
},
"label": {
"type": "string",
"nullable": true,
"description": "Label for the revenue range."
},
"actual": {
"type": "object",
"nullable": true,
"properties": {
"value": {
"type": "number",
"nullable": true,
"description": "Actual revenue amount."
},
"currency": {
"type": "string",
"nullable": true,
"description": "Currency for the revenue amount."
}
}
}
},
"description": "Revenue information of the company."
},
"size": {
"type": "object",
"nullable": true,
"properties": {
"id": {
"type": "number",
"nullable": true,
"description": "Size bracket identifier."
},
"label": {
"type": "string",
"nullable": true,
"description": "Label for the company size range."
},
"actual": {
"type": "number",
"nullable": true,
"description": "Actual number of employees."
}
},
"description": "Company size information."
},
"location": {
"type": "object",
"nullable": true,
"properties": {
"state": {
"type": "object",
"nullable": true,
"properties": {
"_id": {
"type": "string",
"nullable": true,
"description": "MongoDB ObjectId for the state."
},
"type": {
"type": "string",
"nullable": true,
"description": "Type of state location."
},
"name": {
"type": "string",
"nullable": true,
"description": "State name."
},
"code": {
"type": "string",
"nullable": true,
"description": "State code abbreviation."
},
"country": {
"type": "string",
"nullable": true,
"description": "Country the state belongs to."
}
}
},
"country": {
"type": "object",
"nullable": true,
"properties": {
"_id": {
"type": "string",
"nullable": true,
"description": "MongoDB ObjectId for the country."
},
"type": {
"type": "string",
"nullable": true,
"description": "Type of country location."
},
"name": {
"type": "string",
"nullable": true,
"description": "Country name."
},
"code": {
"type": "string",
"nullable": true,
"description": "Country code abbreviation."
}
}
}
},
"description": "Location details of the company."
}
}
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"examples": {
"INVALID_INPUT": {
"value": {
"success": false,
"errorCode": "INVALID_INPUT",
"message": "Bad Request"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"404": {
"description": "Company not found",
"content": {
"application/json": {
"examples": {
"NOT_FOUND": {
"value": {
"success": false,
"errorCode": "NOT_FOUND",
"message": "Company not found"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
}
}
}
},
"/v2/impact/companies/{identifier}/news": {
"get": {
"tags": ["Impact"],
"summary": "Get news for a company",
"description": "Get news for a specific company",
"parameters": [
{
"schema": {
"type": "string",
"minLength": 1,
"description": "Unique identifier of the company."
},
"required": true,
"description": "Unique identifier of the company.",
"name": "identifier",
"in": "path"
}
],
"responses": {
"200": {
"description": "Get news for a specific company response",
"content": {
"application/json": {
"schema": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"nullable": true,
"description": "Title of the news article."
},
"pageUrl": {
"type": "string",
"nullable": true,
"description": "URL link to the news page."
},
"summary": {
"type": "string",
"nullable": true,
"description": "Brief summary of the news content."
},
"sentiment": {
"type": "number",
"nullable": true,
"description": "Sentiment score of the article."
},
"estimatedDate": {
"type": "object",
"nullable": true,
"properties": {
"str": {
"type": "string",
"nullable": true,
"description": "Estimated publication date in string format."
},
"precision": {
"type": "number",
"nullable": true,
"description": "Precision level of the estimated date."
},
"timestamp": {
"type": "number",
"nullable": true,
"description": "Timestamp for the estimated publication date."
}
},
"description": "Estimated date details for the article."
},
"image": {
"type": "string",
"nullable": true,
"description": "Image URL associated with the article."
}
}
},
"description": "List of news articles related to the company."
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"examples": {
"INVALID_INPUT": {
"value": {
"success": false,
"errorCode": "INVALID_INPUT",
"message": "Bad Request"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"404": {
"description": "Company not found",
"content": {
"application/json": {
"examples": {
"NOT_FOUND": {
"value": {
"success": false,
"errorCode": "NOT_FOUND",
"message": "Company not found"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
}
}
}
},
"/v2/collections/{collectionId}/dossiers": {
"post": {
"tags": ["Dossier"],
"summary": "Get dossiers in collection",
"description": "Retrieve dossiers associated with a specific collection with optional filtering and pagination",
"parameters": [
{
"schema": {
"type": "number",
"nullable": true,
"description": "The collection ID to which the new dossier belongs."
},
"required": false,
"description": "The collection ID to which the new dossier belongs.",
"name": "collectionId",
"in": "path"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"filters": {
"type": "object",
"properties": {
"agentIds": {
"type": "array",
"items": {
"type": "string"
},
"description": "Filter agents by the agent's unique identifier."
},
"agentTypes": {
"type": "array",
"items": {
"type": "string",
"enum": ["supplierDossier", "marketInsight"],
"description": "Type of agent, e.g., 'supplierDossier'"
},
"description": "Filter agents by their type, e.g., 'supplierDossier'."
},
"query": {
"type": "string",
"description": "Filter agents by substring match on the original query."
},
"createdBy": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"description": "Cognito user sub."
},
"description": "Filter agents by the unique identifier of the user who created them."
}
},
"description": "Optional filters to apply to the dossiers."
},
"sort": {
"type": "array",
"items": {
"type": "object",
"properties": {
"field": {
"type": "string",
"enum": ["createdAt", "lastModified"],
"description": "Fields to sort agents by."
},
"order": {
"type": "string",
"enum": ["asc", "desc"],
"description": "Sort order according to the specified field."
}
},
"required": ["field", "order"]
},
"description": "Optional sorting criteria for the dossiers."
}
}
}
}
}
},
"responses": {
"200": {
"description": "Dossiers retrieved successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"metadata": {
"type": "object",
"properties": {
"pagination": {
"type": "object",
"properties": {
"totalItems": {
"type": "number",
"description": "Total number of items for the returned dataset after filtering."
},
"totalPages": {
"type": "number",
"description": "Total number of pages for the returned dataset after filtering."
},
"currentPage": {
"type": "number",
"description": "Current page number."
},
"pageSize": {
"type": "number",
"description": "Number of items per page."
},
"unfilteredTotalItems": {
"type": "number",
"description": "Total number of items for the original dataset before filtering."
},
"unfilteredTotalPages": {
"type": "number",
"description": "Total number of pages for the original dataset before filtering."
}
},
"required": ["totalItems", "totalPages", "currentPage", "pageSize"],
"description": "Schema for pagination metadata, including total items, total pages, current page, and page size.",
"example": {
"totalItems": 123,
"totalPages": 13,
"currentPage": 1,
"pageSize": 10,
"unfilteredTotalItems": 196,
"unfilteredTotalPages": 20
}
},
"filters": {
"type": "object",
"properties": {
"agentIds": {
"type": "array",
"items": {
"type": "string"
},
"description": "Filter agents by the agent's unique identifier."
},
"agentTypes": {
"type": "array",
"items": {
"type": "string",
"enum": ["supplierDossier", "marketInsight"],
"description": "Type of agent, e.g., 'supplierDossier'"
},
"description": "Filter agents by their type, e.g., 'supplierDossier'."
},
"query": {
"type": "string",
"description": "Filter agents by substring match on the original query."
},
"createdBy": {
"type": "array",
"items": {
"type": "string",
"format": "uuid",
"description": "Cognito user sub."
},
"description": "Filter agents by the unique identifier of the user who created them."
}
}
},
"sort": {
"type": "array",
"items": {
"type": "object",
"properties": {
"field": {
"type": "string",
"enum": ["createdAt", "lastModified"],
"description": "Fields to sort agents by."
},
"order": {
"type": "string",
"enum": ["asc", "desc"],
"description": "Sort order according to the specified field."
}
},
"required": ["field", "order"]
},
"description": "Sorting criteria for the agents."
}
},
"required": ["pagination", "filters", "sort"]
},
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"agentId": {
"type": "string",
"description": "Unique identifier for the agent"
},
"query": {
"type": "string",
"description": "Original query used to create the agent"
},
"agentType": {
"type": "string",
"enum": ["supplierDossier", "marketInsight"],
"description": "Type of agent, e.g., 'supplierDossier'"
},
"createdAt": {
"type": "string",
"nullable": true,
"format": "date-time",
"description": "Timestamp when the agent was created"
},
"lastModifiedAt": {
"type": "string",
"nullable": true,
"format": "date-time",
"description": "Timestamp when the agent was last modified"
},
"lastTaskId": {
"type": "string",
"nullable": true,
"description": "ID of the last task associated with this agent"
},
"lastTaskStatus": {
"type": "object",
"nullable": true,
"properties": {
"taskId": {
"type": "string",
"description": "Unique identifier for the task"
},
"createdAt": {
"type": "string",
"nullable": true,
"format": "date-time",
"description": "Timestamp when the task was created"
},
"success": {
"type": "boolean",
"nullable": true,
"description": "Indicates whether the task was successful; if `null`, the task is still in progress"
},
"status": {
"type": "string",
"enum": [
"CREATED",
"INITIALIZING",
"ACQUIRING_TARGET",
"GATHERING_RESOURCES",
"GATHERING_INSIGHTS",
"FINDING_COMPETITORS",
"FINALIZING",
"COMPLETED",
"FAILED"
],
"description": "Progress text derived from job metadata"
},
"lastReportedAt": {
"type": "string",
"nullable": true,
"format": "date-time",
"description": "Timestamp of the last status update for the task"
},
"lastReportedBy": {
"type": "string",
"nullable": true,
"description": "Hostname of the worker that last reported the status"
}
},
"required": ["taskId", "createdAt", "status", "lastReportedAt", "lastReportedBy"],
"description": "Status of the last task associated with this agent"
},
"createdBy": {
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid",
"description": "User ID."
},
"fullName": {
"type": "string",
"nullable": true,
"description": "Display name of the user."
}
},
"required": ["id", "fullName"],
"description": "User who created the dossier."
},
"summary": {
"type": "object",
"properties": {
"supplierName": {
"type": "string",
"nullable": true,
"description": "Resolved supplier name from the dossier's target information."
},
"companyDescription": {
"type": "string",
"nullable": true,
"description": "Company description from enrichment data."
},
"headquarters": {
"type": "string",
"nullable": true,
"description": "Headquarters location from enrichment data."
},
"yearEstablished": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
},
{
"nullable": true
}
],
"description": "Year the company was established, from enrichment data."
},
"primaryCategory": {
"type": "string",
"nullable": true,
"description": "Primary category from enrichment data."
}
},
"required": [
"supplierName",
"companyDescription",
"headquarters",
"yearEstablished",
"primaryCategory"
],
"description": "Card summary, present only when requested via `includeSummary` and the dossier has results."
}
},
"required": [
"agentId",
"query",
"agentType",
"lastModifiedAt",
"lastTaskId",
"lastTaskStatus",
"createdBy"
]
},
"description": "List of agents associated with the collection."
}
},
"required": ["metadata", "data"]
}
}
}
},
"400": {
"description": "Bad Request - Invalid input parameters",
"content": {
"application/json": {
"examples": {
"INVALID_INPUT": {
"value": {
"success": false,
"errorCode": "INVALID_INPUT",
"message": "Bad Request - Invalid input parameters"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"403": {
"description": "Forbidden - You do not have permission to list dossiers in this collection",
"content": {
"application/json": {
"examples": {
"FORBIDDEN": {
"value": {
"success": false,
"errorCode": "FORBIDDEN",
"message": "Forbidden - You do not have permission to list dossiers in this collection"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
}
}
}
},
"/v2/collections/{collectionId}/dossier/create": {
"post": {
"tags": ["Dossier"],
"summary": "Create a dossier",
"description": "Create a new dossier in the specified collection using AI to generate supplier information",
"parameters": [
{
"schema": {
"type": "number",
"nullable": true,
"description": "The collection ID to which the new dossier belongs."
},
"required": false,
"description": "The collection ID to which the new dossier belongs.",
"name": "collectionId",
"in": "path"
},
{
"schema": {
"type": "integer",
"minimum": 1,
"description": "Unique identifier of the team from which a quota should be consumed."
},
"required": true,
"description": "Unique identifier of the team from which a quota should be consumed.",
"name": "teamId",
"in": "query"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"agentId": {
"type": "string",
"description": "The agent ID for the dossier."
},
"query": {
"type": "string",
"description": "The query to create the dossier."
},
"shouldUpdate": {
"type": "boolean",
"default": false,
"description": "Whether the dossier should be updated if it already exists. Default is false."
},
"cacheOnly": {
"type": "boolean",
"default": false,
"description": "Whether to only return cached results without querying the agent. Default is false."
},
"ignoreCache": {
"type": "boolean",
"default": false,
"description": "Whether to ignore cached data when creating the dossier and always query the agent. Default is false."
}
},
"required": ["query"]
}
}
}
},
"responses": {
"200": {
"description": "Dossier created successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"agentId": {
"type": "string",
"description": "Unique identifier for the created dossier agent"
},
"jobId": {
"type": "string",
"description": "DynamoDB job ID for tracking this dossier creation"
}
},
"required": ["agentId", "jobId"]
}
}
}
},
"400": {
"description": "Bad Request - Invalid input parameters",
"content": {
"application/json": {
"examples": {
"INVALID_INPUT": {
"value": {
"success": false,
"errorCode": "INVALID_INPUT",
"message": "Bad Request - Invalid input parameters"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"403": {
"description": "Forbidden - You do not have permission to create a dossier in this collection",
"content": {
"application/json": {
"examples": {
"FORBIDDEN": {
"value": {
"success": false,
"errorCode": "FORBIDDEN",
"message": "Forbidden - You do not have permission to create a dossier in this collection"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"500": {
"description": "Internal Server Error - Failed to create dossier",
"content": {
"application/json": {
"examples": {
"INTERNAL_SERVER_ERROR": {
"value": {
"success": false,
"errorCode": "INTERNAL_SERVER_ERROR",
"message": "Internal Server Error - Failed to create dossier"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
}
}
}
},
"/v2/collections/{collectionId}/dossier/{agentId}": {
"patch": {
"tags": ["Dossier"],
"summary": "Update a dossier",
"description": "Update a dossier by adding it to another collection, moving it to another collection, or modifying its properties",
"parameters": [
{
"schema": {
"type": "number",
"nullable": true,
"description": "ID of the collection containing the dossier agent to be managed."
},
"required": false,
"description": "ID of the collection containing the dossier agent to be managed.",
"name": "collectionId",
"in": "path"
},
{
"schema": {
"type": "string",
"description": "Unique identifier for the dossier agent to be managed."
},
"required": true,
"description": "Unique identifier for the dossier agent to be managed.",
"name": "agentId",
"in": "path"
},
{
"schema": {
"type": "integer",
"minimum": 0,
"exclusiveMinimum": true,
"description": "ID of the collection to which the dossier should be added to."
},
"required": false,
"description": "ID of the collection to which the dossier should be added to.",
"name": "addToCollection",
"in": "query"
},
{
"schema": {
"type": "integer",
"minimum": 0,
"exclusiveMinimum": true,
"description": "ID of the target collection to which the dossier should be moved from the collection in the path."
},
"required": false,
"description": "ID of the target collection to which the dossier should be moved from the collection in the path.",
"name": "moveToCollection",
"in": "query"
}
],
"responses": {
"200": {
"description": "Dossier updated successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"metadata": {
"type": "object",
"properties": {
"agentId": {
"type": "string",
"description": "The agent ID"
}
},
"required": ["agentId"]
},
"actionsPerformed": {
"type": "object",
"description": "Actions that were performed on the dossier"
}
},
"required": ["metadata", "actionsPerformed"]
}
}
}
},
"400": {
"description": "Bad Request",
"content": {
"application/json": {
"examples": {
"INVALID_INPUT": {
"value": {
"success": false,
"errorCode": "INVALID_INPUT",
"message": "Bad Request"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"403": {
"description": "Forbidden - You do not have permission to manage dossiers in this collection",
"content": {
"application/json": {
"examples": {
"FORBIDDEN": {
"value": {
"success": false,
"errorCode": "FORBIDDEN",
"message": "Forbidden - You do not have permission to manage dossiers in this collection"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"404": {
"description": "Not Found - Dossier not found",
"content": {
"application/json": {
"examples": {
"NOT_FOUND": {
"value": {
"success": false,
"errorCode": "NOT_FOUND",
"message": "Not Found - Dossier not found"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
}
}
},
"delete": {
"tags": ["Dossier"],
"summary": "Delete a dossier",
"description": "Remove a dossier from the specified collection",
"parameters": [
{
"schema": {
"type": "number",
"nullable": true,
"description": "ID of the collection containing the dossier agent to be managed."
},
"required": false,
"description": "ID of the collection containing the dossier agent to be managed.",
"name": "collectionId",
"in": "path"
},
{
"schema": {
"type": "string",
"description": "Unique identifier for the dossier agent to be managed."
},
"required": true,
"description": "Unique identifier for the dossier agent to be managed.",
"name": "agentId",
"in": "path"
}
],
"responses": {
"200": {
"description": "Dossier deleted successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"metadata": {
"type": "object",
"properties": {
"agentId": {
"type": "string",
"description": "The agent ID"
}
},
"required": ["agentId"]
},
"actionsPerformed": {
"type": "object",
"description": "Actions that were performed on the dossier"
}
},
"required": ["metadata", "actionsPerformed"]
}
}
}
},
"403": {
"description": "Forbidden - You do not have permission to manage dossiers in this collection",
"content": {
"application/json": {
"examples": {
"FORBIDDEN": {
"value": {
"success": false,
"errorCode": "FORBIDDEN",
"message": "Forbidden - You do not have permission to manage dossiers in this collection"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"404": {
"description": "Not Found - Dossier not found",
"content": {
"application/json": {
"examples": {
"NOT_FOUND": {
"value": {
"success": false,
"errorCode": "NOT_FOUND",
"message": "Not Found - Dossier not found"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
}
}
},
"get": {
"tags": ["Dossier"],
"summary": "Get a dossier",
"description": "Retrieve a specific dossier by agent ID and collection ID",
"parameters": [
{
"schema": {
"type": "number",
"nullable": true,
"description": "ID of the collection containing the dossier agent to be managed."
},
"required": false,
"description": "ID of the collection containing the dossier agent to be managed.",
"name": "collectionId",
"in": "path"
},
{
"schema": {
"type": "string",
"description": "Unique identifier for the dossier agent to be managed."
},
"required": true,
"description": "Unique identifier for the dossier agent to be managed.",
"name": "agentId",
"in": "path"
}
],
"responses": {
"200": {
"description": "Dossier retrieved successfully",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"metadata": {
"type": "object",
"description": "Agent metadata information"
},
"data": {
"type": "object",
"description": "Dossier content and results"
}
},
"required": ["metadata", "data"]
}
}
}
},
"403": {
"description": "Forbidden - You do not have permission to manage dossiers in this collection",
"content": {
"application/json": {
"examples": {
"FORBIDDEN": {
"value": {
"success": false,
"errorCode": "FORBIDDEN",
"message": "Forbidden - You do not have permission to manage dossiers in this collection"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"404": {
"description": "Not Found - Dossier not found",
"content": {
"application/json": {
"examples": {
"NOT_FOUND": {
"value": {
"success": false,
"errorCode": "NOT_FOUND",
"message": "Not Found - Dossier not found"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
}
}
}
},
"/v2/events-monitor/events": {
"get": {
"tags": ["Events Monitor"],
"summary": "List events",
"description": "\n Retrieves a list of events based on the provided query parameters. Supports filtering\n by date range, taxonomy matches, impacted entity likelihood and severity scores,\n free-text search, and pagination. By default, only events with at least one impacted\n entity with likelihood 2-3 and severity 2-3 are returned. Score bounds are inclusive.\n Results are sorted by reference count descending, then by the highest\n likelihood * severity product among impacted entities matching the impactedEntity\n filter descending. If no impactedEntity filter is supplied, all impacted entities\n are considered for the secondary sort.\n If date bounds are omitted, the range defaults to the previous UTC day at 00:00\n through the current UTC day at 23:59.\n\n \n **Subscription Endpoint**\n\n This endpoint has a special subscription requirement. Your API Key needs to be\n subscribed to this endpoint in order to access it; otherwise it will return a 403\n Forbidden error. Please contact Forestreet support to get subscribed.\n \n\n An Event is a collection of one or more Observations that all refer to the same\n underlying occurrence. For example, if a company is acquired, there may be multiple\n news articles about the acquisition, and each article would be an Observation.\n However, all of these Observations would be grouped under a single Event that\n represents the acquisition itself.\n\n \n The grouping of Events is subjective to some extent; a different person may group\n Observations differently based on their interpretation. Our system uses a community\n detection algorithm on a graph of Observations linked up by proprietary heuristics to\n determine which Observations belong to the same Event. These may not always align\n with everyone's intuition, and we are continuously working to improve our algorithms\n and welcome user feedback on any misgroupings they observe.\n \n ",
"parameters": [
{
"schema": {
"type": "number",
"minimum": 1,
"maximum": 100,
"default": 10,
"description": "Number of items per page, default is 10, minimum is 1, maximum is 100."
},
"required": false,
"description": "Number of items per page, default is 10, minimum is 1, maximum is 100.",
"name": "pageSize",
"in": "query"
},
{
"schema": {
"type": "number",
"minimum": 1,
"default": 1,
"description": "Current page number, default is 1."
},
"required": false,
"description": "Current page number, default is 1.",
"name": "page",
"in": "query"
},
{
"schema": {
"type": "string",
"description": "Start of lastUpdated date range (ISO 8601). Defaults to the previous UTC day at 00:00. Date-only values default to 00:00 UTC."
},
"required": false,
"description": "Start of lastUpdated date range (ISO 8601). Defaults to the previous UTC day at 00:00. Date-only values default to 00:00 UTC.",
"name": "from",
"in": "query"
},
{
"schema": {
"type": "string",
"description": "End of lastUpdated date range (ISO 8601). Defaults to the current UTC day at 23:59. Date-only values default to 23:59 UTC."
},
"required": false,
"description": "End of lastUpdated date range (ISO 8601). Defaults to the current UTC day at 23:59. Date-only values default to 23:59 UTC.",
"name": "to",
"in": "query"
},
{
"schema": {
"type": "string",
"description": "Comma-separated list of affected datapoint names (OR within, AND with other filters)."
},
"required": false,
"description": "Comma-separated list of affected datapoint names (OR within, AND with other filters).",
"name": "affectedDatapoint",
"in": "query"
},
{
"schema": {
"type": "string",
"description": "Comma-separated list of alert type names (OR within, AND with other filters)."
},
"required": false,
"description": "Comma-separated list of alert type names (OR within, AND with other filters).",
"name": "alertType",
"in": "query"
},
{
"schema": {
"type": "string",
"description": "Comma-separated list of impacted entity names (OR within, AND with other filters)."
},
"required": false,
"description": "Comma-separated list of impacted entity names (OR within, AND with other filters).",
"name": "impactedEntity",
"in": "query"
},
{
"schema": {
"type": "integer",
"nullable": true,
"minimum": 0,
"maximum": 3,
"default": 2,
"description": "Minimum impacted entity likelihood score, inclusive. Defaults to 2. Score scale is 0 to 3."
},
"required": false,
"description": "Minimum impacted entity likelihood score, inclusive. Defaults to 2. Score scale is 0 to 3.",
"name": "minLikelihood",
"in": "query"
},
{
"schema": {
"type": "integer",
"nullable": true,
"minimum": 0,
"maximum": 3,
"default": 3,
"description": "Maximum impacted entity likelihood score, inclusive. Defaults to 3. Score scale is 0 to 3."
},
"required": false,
"description": "Maximum impacted entity likelihood score, inclusive. Defaults to 3. Score scale is 0 to 3.",
"name": "maxLikelihood",
"in": "query"
},
{
"schema": {
"type": "integer",
"nullable": true,
"minimum": 0,
"maximum": 3,
"default": 2,
"description": "Minimum impacted entity severity score, inclusive. Defaults to 2. Score scale is 0 to 3."
},
"required": false,
"description": "Minimum impacted entity severity score, inclusive. Defaults to 2. Score scale is 0 to 3.",
"name": "minSeverity",
"in": "query"
},
{
"schema": {
"type": "integer",
"nullable": true,
"minimum": 0,
"maximum": 3,
"default": 3,
"description": "Maximum impacted entity severity score, inclusive. Defaults to 3. Score scale is 0 to 3."
},
"required": false,
"description": "Maximum impacted entity severity score, inclusive. Defaults to 3. Score scale is 0 to 3.",
"name": "maxSeverity",
"in": "query"
},
{
"schema": {
"type": "string",
"description": "Optional free-text search across event title, summary, keywords, relevant entities, taxonomy matches, and reference titles."
},
"required": false,
"description": "Optional free-text search across event title, summary, keywords, relevant entities, taxonomy matches, and reference titles.",
"name": "search",
"in": "query"
}
],
"responses": {
"200": {
"description": "The response containing pagination metadata, and an array of zero or more events that satisfy the query parameters.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"meta": {
"type": "object",
"properties": {
"totalItems": {
"type": "number",
"description": "Total number of items for the returned dataset after filtering."
},
"totalPages": {
"type": "number",
"description": "Total number of pages for the returned dataset after filtering."
},
"currentPage": {
"type": "number",
"description": "Current page number."
},
"pageSize": {
"type": "number",
"description": "Number of items per page."
},
"unfilteredTotalItems": {
"type": "number",
"description": "Total number of items for the original dataset before filtering."
},
"unfilteredTotalPages": {
"type": "number",
"description": "Total number of pages for the original dataset before filtering."
}
},
"required": ["totalItems", "totalPages", "currentPage", "pageSize"],
"description": "Schema for pagination metadata, including total items, total pages, current page, and page size.",
"example": {
"totalItems": 123,
"totalPages": 13,
"currentPage": 1,
"pageSize": 10,
"unfilteredTotalItems": 196,
"unfilteredTotalPages": 20
}
},
"data": {
"type": "array",
"items": {
"type": "object",
"properties": {
"_id": {
"type": "string",
"description": "Unique identifier for the event",
"example": "69e5bfcd21aab5bcbb62eae4"
},
"title": {
"type": "string",
"description": "Title of the event.\n\nThis is generated by LLM based on any available contents of the referenced Observations, such as their titles and summaries. It is meant to be a concise and human-readable summary of the event, as though it is written by a journalist having been given the same Observation data.",
"example": "China Sees Greater Integration Between Trade and Investment, Creating New Opportunities"
},
"summary": {
"type": "string",
"description": "Summary of the event.\n\nThis is generated by LLM based on any available contents of the referenced Observations, such as their titles and summaries. It is to be an executive summary of the event, capturing the key details and significance of the event in a few sentences for a C-suite audience.\n\nThis field is meant for user consumption, and may not be comprehensive enough for NLP processing.\n\nThe following fields are designed for NLP processing:\n- `vectorIndex.anchorText`\n- `eventSearchKeywords`\n",
"example": "China's foreign trade sector is increasingly integrating trade and investment functions, a trend noted by state broadcaster coverage highlighting evolving policy and market structures. This integration can foster deeper value-chain links, encourage inward and outbound investment tied to trade flows, and create procurement opportunities for multinational firms seeking integrated supply-and-investment strategies. For trading companies and investors, integrated approaches can streamline cross-border operations, facilitate production localization and affect supplier selection and partnership models. The narrative indicates potential opportunities for firms to leverage investment to secure market access, though the story does not provide quantitative data or named project examples."
},
"vectorIndex": {
"type": "object",
"properties": {
"anchorText": {
"type": "string",
"nullable": true,
"description": "An \"anchor text\" is a snippet of text that is used as a reference point for the vector index. It serves as a concise representation of the content of the event, stripped of any named entities or non-embeddable content, reducing an event to a simple vector that captures the core essence of what happened.\n\n This allows for efficient similarity searches for similar events regardless of the specific entities involved, enabling users to find events that are similar in nature even if they involve different companies, people, or other entities.",
"example": "a government narrative promoting closer alignment of trade and investment to spur commercial opportunities"
},
"embeddings": {
"type": "array",
"nullable": true,
"items": {
"type": "number"
},
"description": "An array of numbers representing the vector embeddings of the event's content."
},
"embeddingsModelName": {
"type": "string",
"nullable": true,
"description": "The name of the model used to generate the embeddings."
}
},
"required": ["anchorText"]
},
"eventSearchKeywords": {
"type": "array",
"items": {
"type": "object",
"properties": {
"keyword": {
"type": "string",
"nullable": true
},
"propertySource": {
"type": "string",
"nullable": true,
"enum": ["inferred", "explicit", null],
"description": "Whether the property was inferred by LLM or explicitly extracted from its content. Currently only `inferred` is supported, but we may add `explicit` in the future for properties that are directly extracted from text rather than inferred through LLM reasoning."
}
},
"required": ["keyword", "propertySource"]
},
"description": "A list of keywords that are likely to be relevant for searching for contextual information regarding this event. They are also useful in finding more reportings of the same event. These are extracted from the event's content and can be used as search terms to find additional information about the event, such as news articles, reports, or other relevant documents. They can be used for further context buiding as well as event grouping.",
"example": [
{
"keyword": "China foreign trade",
"propertySource": "inferred"
},
{
"keyword": "investment",
"propertySource": "inferred"
},
{
"keyword": "trade-investment integration",
"propertySource": "inferred"
},
{
"keyword": "supply chain",
"propertySource": "inferred"
},
{
"keyword": "market access",
"propertySource": "inferred"
}
]
},
"relevantEntities": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"nullable": true
},
"entityType": {
"type": "string",
"nullable": true,
"enum": ["company", "category", "country", "location", null],
"description": "The type of the relevant entity."
},
"propertySource": {
"type": "string",
"nullable": true,
"enum": ["inferred", "explicit", null],
"description": "Whether the property was inferred by LLM or explicitly extracted from its content. Currently only `inferred` is supported, but we may add `explicit` in the future for properties that are directly extracted from text rather than inferred through LLM reasoning."
}
},
"required": ["name", "entityType", "propertySource"]
},
"description": "A list of entities relevant to the event. Each entity includes its name, type, and the source of the property.\n \nThese are inferred from the article contents as free text, and is not guaranteed to match the Beroe Data Hub taxonomy.\n\nFor taxonomic matching to Beroe Data Hub entities, please refer to the `taxonomicMatches` field, which providesdetailed information on how the event's contents map to specific entities in ourtaxonomy, along with the rationale and confidence level of each match.",
"example": [
{
"name": "Trade and Investment Integration",
"entityType": "category",
"propertySource": "inferred"
},
{
"name": "Supply Chain Localization",
"entityType": "category",
"propertySource": "inferred"
},
{
"name": "China",
"entityType": "country",
"propertySource": "inferred"
}
]
},
"timestamps": {
"type": "object",
"properties": {
"published": {
"type": "string",
"nullable": true,
"format": "date-time"
},
"recordedStart": {
"type": "string",
"nullable": true,
"format": "date-time"
},
"recordedEnd": {
"type": "string",
"nullable": true,
"format": "date-time"
},
"projectedStart": {
"type": "string",
"nullable": true,
"format": "date-time"
},
"projectedEnd": {
"type": "string",
"nullable": true,
"format": "date-time"
}
},
"description": "Timestamps relevant to the event. The key indicates the type of the timestamp.\n \nAll values must be in UTC and in ISO 8601 format. Not all events will have all types of timestamps; the presence of each timestamp depends on the available information for that event.",
"example": {
"published": "2026-04-20T05:38:41.505Z",
"recordedStart": "2026-04-19T14:03:00.073Z"
}
},
"references": {
"type": "array",
"items": {
"type": "object",
"properties": {
"_id": {
"type": "string",
"description": "Unique identifier for the observation",
"example": "69e5b8d17a3ce8b7e8505aa5"
},
"title": {
"type": "string",
"description": "Title of the observation.\n \nFor news articles, this will typically be the native title of the article from the publisher.",
"example": "China’s foreign trade, investment integration generates greater opportunities"
},
"url": {
"type": "string",
"description": "URL of the observation, if it was sourced and scraped from the internet.",
"example": "https://www.globaltimes.cn/page/202604/1359275.shtml"
}
},
"required": ["_id", "title"]
},
"description": "A list of observations that are referenced by the event. Each observation includes its title and URL (if available). These are the specific pieces of content that the LLM used as source material to generate the event's title and summary."
},
"lastUpdated": {
"type": "string",
"nullable": true,
"format": "date-time",
"description": "The last updated timestamp of the Event, in UTC and ISO 8601 format. This indicates when the Event was last updated in our system, which can be different from the timestamps of the underlying Observations. It is useful for understanding the recency of creation and mutation of the Event information.",
"example": "2026-04-20T05:38:42.448Z"
},
"taxonomicMatches": {
"type": "object",
"properties": {
"affectedDatapoints": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The matched procurement datapoint from the Beroe taxonomy."
},
"subject": {
"type": "string",
"nullable": true,
"description": "The specific subject of the datapoint as mentioned in the source articles, e.g. `crude oil`, `semiconductors`, `shipping services`. Null when no specific subject was identified."
},
"direction": {
"type": "string",
"nullable": true,
"enum": ["up", "down", "fluctuate", "unknown", null],
"description": "The direction of change, or null if the direction could not be determined, or for old legacy data that hasn't been backfilled with direction."
},
"quantity": {
"type": "object",
"nullable": true,
"properties": {
"operator": {
"type": "string",
"enum": [">", "<", ">=", "<=", "=", "~", "range"],
"description": "The comparison operator for the quantified change. Single-value operators (>, <, >=, <=, =, ~) expect one entry in `values`; `range` expects two (lower bound, upper bound)."
},
"values": {
"type": "array",
"items": {
"type": "number"
},
"description": "Numeric values for the operator. One value for point operators (>, <, >=, <=, =, ~); two values [lower, upper] for `range`."
},
"unit": {
"type": "string",
"description": "Unit of the change, e.g. `%`, `USD`, `barrels`."
}
},
"required": ["operator", "values", "unit"],
"description": "The quantified magnitude of the change, if one was extractable from the source articles.",
"example": {
"operator": ">",
"values": [10],
"unit": "%"
}
}
},
"required": ["name", "subject", "direction", "quantity"],
"description": "An exact match of a procurement datapoint from the Beroe taxonomy, together with the direction and optional quantified magnitude of the change.",
"example": {
"name": "Unit Price",
"subject": "crude oil",
"direction": "up",
"quantity": {
"operator": ">",
"values": [10],
"unit": "%"
}
}
},
"example": [
{
"name": "Net Supply",
"subject": null,
"direction": "down",
"quantity": null
},
{
"name": "Unit Price",
"subject": "crude oil",
"direction": "up",
"quantity": {
"operator": ">",
"values": [10],
"unit": "%"
}
}
],
"description": "Taxonomic matches of the event's affected datapoints to our pre-defined taxonomy in Beroe Data Hub.\n\nThis provides a structured way to understand the specific datapoints that are affected by the event, which can be useful for filtering and analyzing events based on their impact on specific aspects of the supply chain.\n\nThe generation of these affected datapoints are not tied to specific alert types or impacted entities; rather, they are generated based on the overall content of the event; downstream consumers should not assume that the affected datapoints and alert types / impacted entities are mapped to each other directly."
},
"alertTypes": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The name of the matched item. This is the canonical name of the item in our system, such as a company name or a category name."
},
"mappedFrom": {
"type": "string",
"description": "The original text from the event's content that was mapped to this item. This is the actual text snippet that was found in the event's content and matched to the canonical item name."
},
"method": {
"type": "string",
"nullable": true,
"description": "The method used to determine the match. This could be a specific NLP technique, a rule-based approach, or a machine learning model. It provides context on how the match was derived."
},
"similarity": {
"type": "number",
"nullable": true,
"description": "A numerical score between 0 and 1 indicating the confidence level of the match, with 1 being a perfect match. This is particularly relevant for matches determined through NLP techniques, where there may be some degree of uncertainty."
},
"rationale": {
"type": "string",
"nullable": true,
"description": "The rationale behind the match, providing additional context or explanation for why the match was made."
}
},
"required": ["name", "mappedFrom", "method", "similarity", "rationale"],
"description": "A fuzzy match result using NLP or LLM techniques to a pre-defined list of values.",
"example": {
"name": "Logistics and Supply Chain",
"mappedFrom": "supply chain dependency",
"method": "llm",
"similarity": 1,
"rationale": "Directly refers to supply chain logistics and dependencies"
}
},
"example": [
{
"name": "Geopolitical and Trade",
"mappedFrom": "geopolitical risk",
"method": "llm",
"similarity": 1,
"rationale": "The candidate covers geopolitical risks affecting trade and diplomatic relations."
},
{
"name": "Logistics and Supply Chain",
"mappedFrom": "supply chain dependency",
"method": "llm",
"similarity": 1,
"rationale": "Directly refers to supply chain logistics and dependencies"
}
],
"description": "Taxonomic matches of the event's alert types to our pre-defined taxonomy in Beroe Data Hub.\n \nThis provides a structured way to understand the types of alerts that need to be evaluated and raised for this event.\n\nThe generation of these alert types are not tied to specific affected datapoints; rather, they are generated based on the overall content of the event; downstream consumers should not assume that the alert types and datapoints are mapped to each other directly."
},
"impactedEntities": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The name of the impacted entity, such as a company, category, country, or location name.",
"example": "Trade Finance Services"
},
"entityType": {
"type": "string",
"enum": ["company", "category", "country", "location"],
"description": "The type of the relevant entity."
},
"mappedFrom": {
"type": "string",
"description": "The original text from the event's content that was mapped to this impacted entity.",
"example": "trade and investment integration: Strategies that coordinate cross-border trade flows with inward or outward investment decisions."
},
"impact": {
"type": "object",
"properties": {
"likelihood": {
"type": "number",
"description": "The likelihood of the impact occurring, on a scale from 0 to 3."
},
"severity": {
"type": "number",
"description": "The severity of the impact if it occurs, on a scale from 0 to 3."
},
"rationale": {
"type": "string",
"description": "The rationale for the assigned likelihood and severity scores."
}
},
"required": ["likelihood", "severity", "rationale"],
"description": "An impact assessment.\n \nThe likelihood and severity scores are typically assigned based on the content of the event and the LLM's understanding of the potential consequences. The rationale provides additional context for these scores, which can be useful for users to understand the reasoning behind the impact assessment.",
"example": {
"likelihood": 2,
"severity": 1,
"rationale": "Policy emphasis may encourage firms to pursue combined trade/investment approaches, creating commercial opportunities."
}
}
},
"required": ["name", "entityType", "mappedFrom", "impact"]
},
"description": "Taxonomic matches of the event's impacted entities to our pre-defined taxonomy in Beroe Data Hub.\n \nSupports company, category, country, and location entities, which can be used for filtering and analysis of events based on the entities they impact.",
"example": [
{
"name": "Trade Finance Services",
"entityType": "category",
"mappedFrom": "trade and investment integration: Strategies that coordinate cross-border trade flows with inward or outward investment decisions.",
"impact": {
"likelihood": 2,
"severity": 1,
"rationale": "Policy emphasis may encourage firms to pursue combined trade/investment approaches, creating commercial opportunities."
}
},
{
"name": "Investment Management",
"entityType": "category",
"mappedFrom": "trade and investment integration: Strategies that coordinate cross-border trade flows with inward or outward investment decisions.",
"impact": {
"likelihood": 2,
"severity": 1,
"rationale": "Policy emphasis may encourage firms to pursue combined trade/investment approaches, creating commercial opportunities."
}
},
{
"name": "Strategy Consulting",
"entityType": "category",
"mappedFrom": "trade and investment integration: Strategies that coordinate cross-border trade flows with inward or outward investment decisions.",
"impact": {
"likelihood": 2,
"severity": 1,
"rationale": "Policy emphasis may encourage firms to pursue combined trade/investment approaches, creating commercial opportunities."
}
}
]
}
},
"required": ["affectedDatapoints", "alertTypes", "impactedEntities"],
"description": "Taxonomic matches of the event's affected datapoints, alert types, and impacted entities to our pre-defined taxonomy in Beroe Data Hub.\n \nAffected datapoints include the matched datapoint name, optional subject, direction of change, and optional quantified magnitude. Alert types and impacted entities retain their matching metadata. This provides a structured way to understand how the event's contents relate to specific concepts in our taxonomy, which can be useful for filtering, searching, and analyzing events based on these standardized categories."
}
},
"required": ["_id", "title", "summary", "vectorIndex", "lastUpdated"]
},
"description": "A list of events matching the query parameters, within the specified page and page size."
}
},
"required": ["meta", "data"]
}
}
}
},
"400": {
"description": "Invalid query parameters",
"content": {
"application/json": {
"examples": {
"QUERY_VALIDATION_FAILED": {
"value": {
"success": false,
"errorCode": "QUERY_VALIDATION_FAILED",
"message": "Invalid query parameters"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"401": {
"description": "Unauthorized access - API Key is missing or invalid",
"content": {
"application/json": {
"examples": {
"UNAUTHORISED": {
"value": {
"success": false,
"errorCode": "UNAUTHORISED",
"message": "Unauthorized access - API Key is missing or invalid"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"403": {
"description": "API Key not subscribed to this endpoint",
"content": {
"application/json": {
"examples": {
"FORBIDDEN": {
"value": {
"success": false,
"errorCode": "FORBIDDEN",
"message": "API Key not subscribed to this endpoint"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"examples": {
"INTERNAL_SERVER_ERROR": {
"value": {
"success": false,
"errorCode": "INTERNAL_SERVER_ERROR",
"message": "Internal Server Error"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
}
}
}
},
"/v2/events-monitor/observation/{observationId}": {
"get": {
"tags": ["Events Monitor"],
"summary": "Get an Observation",
"description": "\n Retrieves a single observation based on the provided observation ID.\n\n \n **Subscription Endpoint**\n\n This endpoint has a special subscription requirement. Your API Key needs to be\n subscribed to this endpoint in order to access it; otherwise it will return a 403\n Forbidden error. Please contact Forestreet support to get subscribed.\n \n\n An Observation is a piece of information or data point that has been collected and\n stored in our system. It serves as the foundational unit of information to join\n together as Events, and can represent various types of data such as news articles,\n social media posts, analyst reports, or any other relevant information that we want to\n track and analyze. Each observation contains metadata about its source, content,\n publication time, and other relevant attributes that allow us to process and analyze\n it effectively.\n ",
"parameters": [
{
"schema": {
"type": "string",
"description": "The unique identifier of the observation",
"example": "69e89d74df2753cf786ef002"
},
"required": true,
"description": "The unique identifier of the observation",
"name": "observationId",
"in": "path"
}
],
"responses": {
"200": {
"description": "The response containing pagination metadata, and an array of zero or more events that satisfy the query parameters.",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"_id": {
"type": "string",
"description": "Unique identifier for the observation",
"example": "69e89d74df2753cf786ef002"
},
"dedupeId": {
"type": "string",
"description": "A deduplication identifier for the observation, used to identify and merge duplicate observations.",
"example": "NewsArticle::url(https://www.dw.com/en/czechias-lithium-mine-plans-spark-resistance/video-76878114)"
},
"sourceService": {
"type": "string",
"description": "The service from which the observation was sourced, e.g. 'News Monitor'.",
"example": "News Monitor"
},
"title": {
"type": "string",
"description": "Title of the observation. For news articles, this will typically be the native title of the article from the publisher.",
"example": "Czechia's lithium mine plans spark resistance"
},
"content": {
"type": "array",
"items": {
"type": "string"
},
"description": "An array of text snippets that provide the content of the observation. For news articles, this may include the article summary, key sentences, or other relevant text extracted from the article. If an article failed to scrape, it may only contain 1 content item which is the search engine snippet.\n\nThe content items may have been pruned before being stored on our system, so that only the most relevant information is retained. It is not guaranteed to be the full text of the original source.",
"example": [
"Plans to mine lithium in Cinovec, a mountain town on the Czech-German border, are dividing local communities. While the project promises jobs and investment...",
"Plans to mine lithium in Cinovec, a mountain town on the Czech-German border, are dividing local communities. While the project promises jobs and investment, residents fear it could bring pollution and harm tourism.",
"Czechia's lithium mine plans spark resistance",
"In Cinovec, a small mountain town on the Czech- German border, plans to mine lithium have divided locals.",
"Known for its clean air, forests and spa tourism, the region around Cinovec has reportedly got one of Europe's largest lithium deposits, a resource seen as vital to the green energy transition.",
"According to Geomet, the company behind the project, mining will bring jobs and economic growth. But many residents fear it could harm the region's fragile ecosystem, which is still recovering from decades of coal mining.",
"As miners scour Zambia for metals used in sustainable energy, locals are dealing with unchecked pollution."
]
},
"textEmbedding": {
"type": "array",
"items": {
"type": "number"
},
"description": "An array of numbers representing the embedding vector for the observation's content.",
"example": [0.123, -0.456, 0.789]
},
"weight": {
"type": "object",
"additionalProperties": {
"type": "number"
},
"description": "A dictionary of weights for the observation, where the keys are weight names (e.g. 'Media Bias Multiplier') and the values are the corresponding weight values. These weights can be used to adjust the importance of the observation in various algorithms, such as event clustering or impact assessment.",
"example": {
"Media Bias Multiplier": 1.992
}
},
"publishedAt": {
"type": "string",
"nullable": true,
"format": "date-time",
"description": "The date and time when the observation was published or recorded. These are always UTC.",
"example": "2026-04-21T17:02:22.885Z"
},
"addedAt": {
"type": "string",
"nullable": true,
"format": "date-time",
"description": "The date and time when the observation was added to our system. These are always UTC.",
"example": "2026-04-22T10:02:22.885Z"
},
"clusterLabel": {
"type": "object",
"properties": {
"label": {
"type": "number",
"description": "The cluster label, represented as an integer. Observations with the same cluster label are considered to belong to the same event cluster.",
"example": 3
},
"method": {
"type": "string",
"description": "The method used to determine the cluster label. For internal use only, the exact value of this field can change without notice.",
"example": "Leiden"
}
},
"required": ["label", "method"],
"description": "The cluster label assigned to this observation, if it has been clustered."
},
"url": {
"type": "string",
"format": "uri",
"description": "URL of the observation, if it was sourced and scraped from the internet. Only available on publicly sourced observations such as News Articles.",
"example": "https://www.dw.com/en/czechias-lithium-mine-plans-spark-resistance/video-76878114"
}
},
"required": [
"_id",
"dedupeId",
"sourceService",
"title",
"content",
"textEmbedding",
"weight",
"publishedAt",
"addedAt"
],
"additionalProperties": {
"nullable": true
},
"description": "The response schema for the Get Observation endpoint."
}
}
}
},
"400": {
"description": "Invalid query parameters",
"content": {
"application/json": {
"examples": {
"QUERY_VALIDATION_FAILED": {
"value": {
"success": false,
"errorCode": "QUERY_VALIDATION_FAILED",
"message": "Invalid query parameters"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"401": {
"description": "Unauthorized access - API Key is missing or invalid",
"content": {
"application/json": {
"examples": {
"UNAUTHORISED": {
"value": {
"success": false,
"errorCode": "UNAUTHORISED",
"message": "Unauthorized access - API Key is missing or invalid"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"403": {
"description": "API Key not subscribed to this endpoint",
"content": {
"application/json": {
"examples": {
"FORBIDDEN": {
"value": {
"success": false,
"errorCode": "FORBIDDEN",
"message": "API Key not subscribed to this endpoint"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"404": {
"description": "Observation with the given ID not found",
"content": {
"application/json": {
"examples": {
"NOT_FOUND": {
"value": {
"success": false,
"errorCode": "NOT_FOUND",
"message": "Observation with the given ID not found"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
},
"500": {
"description": "Internal Server Error",
"content": {
"application/json": {
"examples": {
"INTERNAL_SERVER_ERROR": {
"value": {
"success": false,
"errorCode": "INTERNAL_SERVER_ERROR",
"message": "Internal Server Error"
}
}
},
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"enum": [false]
},
"errorCode": {
"type": "string",
"enum": [
"USER_NOT_CONFIRMED",
"INVALID_CREDENTIALS",
"INCOMPLETE_CREDENTIALS",
"INVALID_SESSION_TOKEN",
"FORCE_CHANGE_PASSWORD",
"PASSWORD_RESET_REQUIRED",
"PASSWORD_EXPIRED",
"CODE_EXPIRED",
"SESSION_EXPIRED",
"UNAUTHORISED",
"AUTHENTICATOR_ERROR",
"SSO_ACCOUNT",
"FORBIDDEN",
"METHOD_NOT_ALLOWED",
"INVALID_INPUT",
"PATH_VALIDATION_FAILED",
"QUERY_VALIDATION_FAILED",
"BODY_VALIDATION_FAILED",
"RESPONSE_VALIDATION_FAILED",
"INVALID_OR_MALFORMED_JSON",
"INTERNAL_SERVER_ERROR",
"CONFIGURATION_ERROR",
"SERVICE_UNAVAILABLE",
"NOT_FOUND",
"CONFLICT",
"LIMIT_EXCEEDED",
"REVIEW_ALREADY_PENDING",
"REVIEW_NOT_PENDING",
"REVIEW_PENDING",
"REVIEW_INSUFFICIENT_DOMAINS",
"QUOTA_EXCEEDED",
"UNSUPPORTED_ENDPOINT_VERSION",
"ENDPOINT_NOT_FOUND",
"ENDPOINT_ALREADY_EXISTS"
]
},
"message": {
"type": "string"
},
"detail": {
"type": "object",
"additionalProperties": {
"nullable": true
}
}
},
"required": ["success", "errorCode"]
}
}
}
}
}
}
},
"/v2/assets/icons/{iconName}": {
"get": {
"tags": ["Assets"],
"summary": "Get an iconographic symbol by name",
"description": "Attempts to retrieve an iconographic symbol by its name from the Noun Project API.\n \n This endpoint supports both JSON and PNG responses.\n\n If the icon is not found and a PNG response is requested, it will return a fallback icon in form of\n a magnifying glass.",
"parameters": [
{
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "Name of the icon to retrieve."
},
"required": true,
"description": "Name of the icon to retrieve.",
"name": "iconName",
"in": "path"
},
{
"schema": {
"type": "string",
"minLength": 1,
"maxLength": 100,
"description": "Fallback icon name to use if the requested icon is not found."
},
"required": false,
"description": "Fallback icon name to use if the requested icon is not found.",
"name": "fallbackTo",
"in": "query"
},
{
"schema": {
"type": "string",
"enum": ["image/png", "application/json"],
"default": "image/png",
"description": "Content type for the image endpoint. Defaults to 'image/png'. Use 'application/json' to get base64 encoded image."
},
"required": false,
"description": "Content type for the image endpoint. Defaults to 'image/png'. Use 'application/json' to get base64 encoded image.",
"name": "contentType",
"in": "query"
}
],
"responses": {
"200": {
"description": "Iconographic symbol by name response",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"description": "Indicates if the asset was successfully retrieved."
},
"data": {
"type": "string",
"description": "Base64 encoded asset data."
}
},
"required": ["success", "data"]
}
}
}
},
"404": {
"description": "Icon not found",
"content": {
"application/json": {
"schema": {
"type": "object",
"properties": {
"success": {
"type": "boolean",
"description": "Indicates if the asset was successfully retrieved."
},
"data": {
"type": "string",
"description": "Base64 encoded asset data."
}
},
"required": ["success", "data"]
}
}
}
}
}
}
},
"/v2/assets/logos/{domain}": {
"get": {
"tags": ["Assets"],
"summary": "Get a company logo by domain",
"description": "Attempts to retrieve a company logo by its domain. Cached logos are stored in MySQL for 90 days before they are refreshed via the logo.dev API.\n\n This endpoint supports both JSON and PNG responses.\n\n The path should contain the domain name.\n\n Example: google.com\n\n If the logo cannot be served and a PNG response is requested, a magnifying-glass fallback icon is returned.",
"parameters": [
{
"schema": {
"type": "string",
"pattern": "^(?!-)[a-zA-Z0-9-]{1,63}(?