diff --git a/api-reference/openapi.json b/api-reference/openapi.json index 2393a65..eb72b9a 100644 --- a/api-reference/openapi.json +++ b/api-reference/openapi.json @@ -5963,6 +5963,26 @@ } } } + }, + "400": { + "description": "Validation error (e.g., missing required query parameter `q`)", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ResearchErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication failed \u2014 invalid or missing API key", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ResearchErrorResponse" + } + } + } } } } @@ -5991,6 +6011,26 @@ } } } + }, + "400": { + "description": "Validation error (e.g., missing `artist` parameter)", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ResearchErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication failed \u2014 invalid or missing API key", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ResearchErrorResponse" + } + } + } } } } @@ -6034,6 +6074,26 @@ } } } + }, + "400": { + "description": "Validation error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ResearchErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication failed \u2014 invalid or missing API key", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ResearchErrorResponse" + } + } + } } } } @@ -6062,6 +6122,26 @@ } } } + }, + "400": { + "description": "Validation error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ResearchErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication failed \u2014 invalid or missing API key", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ResearchErrorResponse" + } + } + } } } } @@ -6083,37 +6163,51 @@ "name": "country", "in": "query", "required": false, - "description": "Two-letter country code (e.g. US, GB, DE).", + "description": "Two-letter ISO country code (e.g. US, GB, DE). Defaults to `US` if omitted.", "schema": { - "type": "string" + "type": "string", + "default": "US", + "minLength": 2, + "maxLength": 2, + "pattern": "^[A-Z]{2}$" } }, { "name": "interval", "in": "query", "required": false, - "description": "Time interval (e.g. daily, weekly).", + "description": "Time interval: `daily` or `weekly`. Defaults to `daily`.", "schema": { - "type": "string" + "type": "string", + "default": "daily", + "enum": [ + "daily", + "weekly" + ] } }, { "name": "type", "in": "query", "required": false, - "description": "Chart type (varies by platform).", + "description": "Chart type (e.g. `regional`, `viral`). Defaults to `regional`.", "schema": { - "type": "string" + "type": "string", + "default": "regional", + "enum": [ + "regional", + "viral" + ] } }, { "name": "latest", "in": "query", "required": false, - "description": "Return only the latest chart.", + "description": "Return only the latest chart. Defaults to `true`.", "schema": { - "type": "string", - "default": "true" + "type": "boolean", + "default": true } } ], @@ -6127,6 +6221,26 @@ } } } + }, + "400": { + "description": "Validation error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ResearchErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication failed \u2014 invalid or missing API key", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ResearchErrorResponse" + } + } + } } } } @@ -6155,6 +6269,26 @@ } } } + }, + "400": { + "description": "Validation error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ResearchErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication failed \u2014 invalid or missing API key", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ResearchErrorResponse" + } + } + } } } } @@ -6199,6 +6333,26 @@ } } } + }, + "400": { + "description": "Validation error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ResearchErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication failed \u2014 invalid or missing API key", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ResearchErrorResponse" + } + } + } } } } @@ -6226,6 +6380,26 @@ } } } + }, + "400": { + "description": "Validation error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ResearchErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication failed \u2014 invalid or missing API key", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ResearchErrorResponse" + } + } + } } } } @@ -6297,13 +6471,33 @@ } } } + }, + "400": { + "description": "Validation error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ResearchErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication failed \u2014 invalid or missing API key", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ResearchErrorResponse" + } + } + } } } } }, "/api/research/enrich": { "post": { - "description": "Enrich an entity with structured data from web research. Provide a description of who or what to research and a JSON schema defining the fields to extract. Returns typed data with citations.", + "description": "Enrich an entity with structured data from web research. Provide a description of who or what to research and a JSON schema defining the fields to extract. Returns typed data with citations. **Important:** The `schema` object must include `\"type\": \"object\"` at the top level \u2014 requests without an explicit type will be rejected.", "requestBody": { "required": true, "content": { @@ -6324,6 +6518,26 @@ } } } + }, + "400": { + "description": "Validation error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ResearchErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication failed \u2014 invalid or missing API key", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ResearchErrorResponse" + } + } + } } } } @@ -6351,6 +6565,26 @@ } } } + }, + "400": { + "description": "Validation error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ResearchErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication failed \u2014 invalid or missing API key", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ResearchErrorResponse" + } + } + } } } } @@ -6368,6 +6602,26 @@ } } } + }, + "400": { + "description": "Validation error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ResearchErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication failed \u2014 invalid or missing API key", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ResearchErrorResponse" + } + } + } } } } @@ -6385,6 +6639,26 @@ } } } + }, + "400": { + "description": "Validation error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ResearchErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication failed \u2014 invalid or missing API key", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ResearchErrorResponse" + } + } + } } } } @@ -6413,6 +6687,26 @@ } } } + }, + "400": { + "description": "Validation error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ResearchErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication failed \u2014 invalid or missing API key", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ResearchErrorResponse" + } + } + } } } } @@ -6441,6 +6735,26 @@ } } } + }, + "400": { + "description": "Validation error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ResearchErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication failed \u2014 invalid or missing API key", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ResearchErrorResponse" + } + } + } } } } @@ -6469,6 +6783,26 @@ } } } + }, + "400": { + "description": "Validation error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ResearchErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication failed \u2014 invalid or missing API key", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ResearchErrorResponse" + } + } + } } } } @@ -6522,6 +6856,26 @@ } } } + }, + "400": { + "description": "Validation error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ResearchErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication failed \u2014 invalid or missing API key", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ResearchErrorResponse" + } + } + } } } } @@ -6550,6 +6904,26 @@ } } } + }, + "400": { + "description": "Validation error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ResearchErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication failed \u2014 invalid or missing API key", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ResearchErrorResponse" + } + } + } } } } @@ -6577,6 +6951,26 @@ } } } + }, + "400": { + "description": "Validation error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ResearchErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication failed \u2014 invalid or missing API key", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ResearchErrorResponse" + } + } + } } } } @@ -6621,6 +7015,26 @@ } } } + }, + "400": { + "description": "Validation error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ResearchErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication failed \u2014 invalid or missing API key", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ResearchErrorResponse" + } + } + } } } } @@ -6715,6 +7129,26 @@ } } } + }, + "400": { + "description": "Validation error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ResearchErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication failed \u2014 invalid or missing API key", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ResearchErrorResponse" + } + } + } } } } @@ -6743,6 +7177,26 @@ } } } + }, + "400": { + "description": "Validation error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ResearchErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication failed \u2014 invalid or missing API key", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ResearchErrorResponse" + } + } + } } } } @@ -6760,6 +7214,26 @@ } } } + }, + "400": { + "description": "Validation error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ResearchErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication failed \u2014 invalid or missing API key", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ResearchErrorResponse" + } + } + } } } } @@ -6788,6 +7262,26 @@ } } } + }, + "400": { + "description": "Validation error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ResearchErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication failed \u2014 invalid or missing API key", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ResearchErrorResponse" + } + } + } } } } @@ -6881,6 +7375,26 @@ } } } + }, + "400": { + "description": "Validation error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ResearchErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication failed \u2014 invalid or missing API key", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ResearchErrorResponse" + } + } + } } } } @@ -6909,6 +7423,26 @@ } } } + }, + "400": { + "description": "Validation error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ResearchErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication failed \u2014 invalid or missing API key", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ResearchErrorResponse" + } + } + } } } } @@ -6937,6 +7471,26 @@ } } } + }, + "400": { + "description": "Validation error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ResearchErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication failed \u2014 invalid or missing API key", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ResearchErrorResponse" + } + } + } } } } @@ -6953,15 +7507,35 @@ "schema": { "type": "string" } - } - ], - "responses": { - "200": { - "description": "Social and streaming URLs", + } + ], + "responses": { + "200": { + "description": "Social and streaming URLs", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ResearchUrlsResponse" + } + } + } + }, + "400": { + "description": "Validation error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ResearchErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication failed \u2014 invalid or missing API key", "content": { "application/json": { "schema": { - "$ref": "#/components/schemas/ResearchUrlsResponse" + "$ref": "#/components/schemas/ResearchErrorResponse" } } } @@ -6993,6 +7567,26 @@ } } } + }, + "400": { + "description": "Validation error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ResearchErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication failed \u2014 invalid or missing API key", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ResearchErrorResponse" + } + } + } } } } @@ -7020,6 +7614,26 @@ } } } + }, + "400": { + "description": "Validation error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ResearchErrorResponse" + } + } + } + }, + "401": { + "description": "Authentication failed \u2014 invalid or missing API key", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/ResearchErrorResponse" + } + } + } } } } @@ -14344,7 +14958,8 @@ "enum": [ "success", "error" - ] + ], + "example": "success" }, "albums": { "type": "array", @@ -14356,27 +14971,47 @@ }, "ResearchAudienceResponse": { "type": "object", - "description": "Audience demographics breakdown \u2014 age ranges, gender split, and country distribution for the specified platform.", + "description": "Audience demographics from Chartmetric \u2014 includes gender breakdown, age-by-gender splits, top countries and cities, and brand affinities. Over 20 fields may be returned; only the most common are listed here.", "properties": { "status": { - "type": "string" + "type": "string", + "example": "success" }, - "age": { + "audience_genders": { "type": "array", - "description": "Age range breakdown", + "description": "Gender breakdown with percentages.", "items": { "type": "object", "additionalProperties": true } }, - "gender": { - "type": "object", - "description": "Gender split percentages", - "additionalProperties": true + "audience_genders_per_age": { + "type": "array", + "description": "Gender split per age bracket.", + "items": { + "type": "object", + "additionalProperties": true + } + }, + "top_countries": { + "type": "array", + "description": "Top countries by audience share.", + "items": { + "type": "object", + "additionalProperties": true + } + }, + "top_cities": { + "type": "array", + "description": "Top cities by audience concentration.", + "items": { + "type": "object", + "additionalProperties": true + } }, - "countries": { + "audience_brand_affinities": { "type": "array", - "description": "Top countries by audience share", + "description": "Brand affinity scores for the audience.", "items": { "type": "object", "additionalProperties": true @@ -14390,13 +15025,10 @@ "description": "Career timeline \u2014 milestones, trajectory, and career stage history.", "properties": { "status": { - "type": "string" - }, - "career_stage": { "type": "string", - "description": "Current career stage (e.g., 'Mid-Level', 'Superstar')" + "example": "success" }, - "data": { + "career": { "type": "array", "description": "Career timeline data points", "items": { @@ -14404,8 +15036,7 @@ "additionalProperties": true } } - }, - "additionalProperties": true + } }, "ResearchChartsResponse": { "type": "object", @@ -14415,7 +15046,8 @@ "enum": [ "success", "error" - ] + ], + "example": "success" }, "data": { "type": "object", @@ -14449,7 +15081,8 @@ "enum": [ "success", "error" - ] + ], + "example": "success" }, "cities": { "type": "array", @@ -14468,7 +15101,8 @@ "enum": [ "success", "error" - ] + ], + "example": "success" }, "name": { "type": "string" @@ -14514,7 +15148,8 @@ "enum": [ "success", "error" - ] + ], + "example": "success" }, "content": { "type": "string", @@ -14571,7 +15206,8 @@ "enum": [ "success", "error" - ] + ], + "example": "success" }, "artists": { "type": "array", @@ -14594,8 +15230,26 @@ }, "schema": { "type": "object", - "description": "JSON schema defining the fields to extract.", - "additionalProperties": true + "description": "JSON schema defining the fields to extract. Must include `\"type\": \"object\"` at the top level.", + "additionalProperties": true, + "properties": { + "type": { + "type": "string", + "enum": [ + "object" + ], + "description": "Must be \"object\"" + }, + "properties": { + "type": "object", + "description": "Field definitions to extract", + "additionalProperties": true + } + }, + "required": [ + "type", + "properties" + ] }, "processor": { "type": "string", @@ -14614,36 +15268,29 @@ "properties": { "status": { "type": "string", - "enum": [ - "success", - "error" - ] + "example": "success" }, "output": { "type": "object", "description": "Structured data matching the provided schema.", "additionalProperties": true }, - "research_basis": { - "type": "object", - "properties": { - "citations": { - "type": "array", - "items": { - "type": "object", - "properties": { - "url": { - "type": "string", - "format": "uri" - }, - "title": { - "type": "string" - }, - "field": { - "type": "string", - "description": "Which output field this citation supports." - } - } + "citations": { + "type": "array", + "description": "Source citations supporting the enriched output.", + "items": { + "type": "object", + "properties": { + "url": { + "type": "string", + "format": "uri" + }, + "title": { + "type": "string" + }, + "field": { + "type": "string", + "description": "Which output field this citation supports." } } } @@ -14678,13 +15325,18 @@ }, "ResearchExtractResponse": { "type": "object", + "required": [ + "status", + "results" + ], "properties": { "status": { "type": "string", "enum": [ "success", "error" - ] + ], + "example": "success" }, "results": { "type": "array", @@ -14697,7 +15349,7 @@ "items": { "type": "object" }, - "description": "URLs that failed to extract." + "description": "URLs that failed to extract. Only present when one or more URLs could not be processed." } } }, @@ -14757,7 +15409,8 @@ "enum": [ "success", "error" - ] + ], + "example": "success" }, "festivals": { "type": "array", @@ -14786,7 +15439,8 @@ "enum": [ "success", "error" - ] + ], + "example": "success" }, "genres": { "type": "array", @@ -14814,7 +15468,8 @@ "enum": [ "success", "error" - ] + ], + "example": "success" }, "insights": { "type": "array", @@ -14826,13 +15481,37 @@ }, "ResearchInstagramPostsResponse": { "type": "object", - "description": "Top Instagram posts and reels sorted by engagement.", + "description": "Top Instagram posts and reels sorted by engagement. Fields are returned directly from Chartmetric's DeepSocial integration.", "properties": { "status": { - "type": "string" + "type": "string", + "example": "success" }, - "posts": { + "top_posts": { + "type": "array", + "description": "Top posts ranked by engagement.", + "items": { + "type": "object", + "properties": { + "url": { + "type": "string" + }, + "likes": { + "type": "integer" + }, + "comments": { + "type": "integer" + }, + "timestamp": { + "type": "string" + } + }, + "additionalProperties": true + } + }, + "top_reels": { "type": "array", + "description": "Top reels ranked by engagement.", "items": { "type": "object", "properties": { @@ -14857,33 +15536,41 @@ }, "ResearchLookupResponse": { "type": "object", - "description": "Artist profile resolved from a platform URL or ID.", + "description": "Artist profile resolved from a platform URL or ID. Cross-platform IDs are nested inside a `data` object.", "properties": { "status": { - "type": "string" - }, - "id": { - "type": "integer", - "description": "Chartmetric artist ID" - }, - "spotify_id": { - "type": "string" - }, - "apple_music_id": { - "type": "string" + "type": "string", + "example": "success" }, - "deezer_id": { - "type": "string" + "data": { + "type": "object", + "description": "Cross-platform artist identifiers returned by Chartmetric.", + "properties": { + "id": { + "type": "integer", + "description": "Chartmetric artist ID" + }, + "spotify_id": { + "type": "string" + }, + "apple_music_id": { + "type": "string" + }, + "deezer_id": { + "type": "string" + } + }, + "additionalProperties": true } - }, - "additionalProperties": true + } }, "ResearchMetricsResponse": { "type": "object", "description": "Time-series metrics for a specific platform. Shape varies by source \u2014 typically an array of data points with timestamps and values (followers, listeners, views, etc.).", "properties": { "status": { - "type": "string" + "type": "string", + "example": "success" }, "data": { "type": "array", @@ -14929,7 +15616,8 @@ "enum": [ "success", "error" - ] + ], + "example": "success" }, "milestones": { "type": "array", @@ -14966,7 +15654,8 @@ "enum": [ "success", "error" - ] + ], + "example": "success" }, "results": { "type": "array", @@ -14988,11 +15677,26 @@ "format": "uri", "description": "Profile URL (often LinkedIn)." }, + "id": { + "type": "string", + "description": "Unique result identifier from the search provider." + }, + "publishedDate": { + "type": "string", + "nullable": true, + "description": "Date the profile or page was published." + }, + "author": { + "type": "string", + "nullable": true, + "description": "Author of the page, if available." + }, "highlights": { "type": "array", "items": { "type": "string" }, + "nullable": true, "description": "Key excerpts from the profile." }, "summary": { @@ -15046,7 +15750,8 @@ "description": "Playlist metadata \u2014 name, description, follower count, track count, and curator info.", "properties": { "status": { - "type": "string" + "type": "string", + "example": "success" }, "name": { "type": "string" @@ -15077,7 +15782,8 @@ "enum": [ "success", "error" - ] + ], + "example": "success" }, "placements": { "type": "array", @@ -15092,7 +15798,8 @@ "description": "Full artist profile \u2014 bio, genres, social links, label, images, and basic stats.", "properties": { "status": { - "type": "string" + "type": "string", + "example": "success" }, "name": { "type": "string" @@ -15142,7 +15849,8 @@ "enum": [ "success", "error" - ] + ], + "example": "success" }, "stations": { "type": "array", @@ -15162,7 +15870,8 @@ "enum": [ "success", "error" - ] + ], + "example": "success" }, "rank": { "type": "integer", @@ -15179,7 +15888,8 @@ "enum": [ "success", "error" - ] + ], + "example": "success" }, "results": { "type": "array", @@ -15247,7 +15957,8 @@ "enum": [ "success", "error" - ] + ], + "example": "success" }, "artists": { "type": "array", @@ -15284,7 +15995,8 @@ "description": "Track metadata \u2014 title, artist, album, release date, popularity, and platform IDs.", "properties": { "status": { - "type": "string" + "type": "string", + "example": "success" }, "name": { "type": "string" @@ -15316,7 +16028,8 @@ "enum": [ "success", "error" - ] + ], + "example": "success" }, "tracks": { "type": "array", @@ -15347,7 +16060,8 @@ "enum": [ "success", "error" - ] + ], + "example": "success" }, "urls": { "type": "array", @@ -15395,7 +16109,8 @@ "enum": [ "success", "error" - ] + ], + "example": "success" }, "venues": { "type": "array", @@ -15437,10 +16152,7 @@ "properties": { "status": { "type": "string", - "enum": [ - "success", - "error" - ] + "example": "success" }, "results": { "type": "array", @@ -15454,8 +16166,19 @@ "url": { "type": "string" }, - "content": { - "type": "string" + "snippet": { + "type": "string", + "description": "Content snippet from the search result." + }, + "date": { + "type": "string", + "nullable": true, + "description": "Publication date if available." + }, + "last_updated": { + "type": "string", + "nullable": true, + "description": "Last updated date if available." } } } @@ -15465,6 +16188,28 @@ "description": "Results formatted as markdown for easy reading." } } + }, + "ResearchErrorResponse": { + "type": "object", + "required": [ + "status", + "error" + ], + "description": "Error response returned by all research endpoints for validation failures (400) and authentication errors (401).", + "properties": { + "status": { + "type": "string", + "enum": [ + "error" + ], + "example": "error" + }, + "error": { + "type": "string", + "description": "Human-readable error message describing what went wrong.", + "example": "Missing required parameter: artist" + } + } } }, "securitySchemes": { @@ -15486,4 +16231,4 @@ } } } -} \ No newline at end of file +} diff --git a/cli.mdx b/cli.mdx index f64a361..03b5d9f 100644 --- a/cli.mdx +++ b/cli.mdx @@ -316,7 +316,7 @@ See [`GET /api/research/venues`](/api-reference/research/venues). ### Rank -Get an artist's global Chartmetric ranking. +Get an artist's global ranking across platforms. ```bash recoup research rank "Drake" @@ -347,7 +347,7 @@ See [`GET /api/research/charts`](/api-reference/research/charts). ### Radio stations -List radio stations tracked by Chartmetric. +List tracked radio stations. ```bash recoup research radio @@ -376,13 +376,13 @@ recoup research web "Phoebe Bridgers fan community psychographics" See [`POST /api/research/web`](/api-reference/research/web). -### Deep research report +### Deep web research -Comprehensive multi-source research that synthesizes information from across the web into a cited report. +Deep web research that synthesizes information from across the web into a cited report. ```bash -recoup research report "Drake" -recoup research report "Tell me everything about Phoebe Bridgers — bio, streaming metrics, fan base, competitive landscape, and revenue opportunities" +recoup research deep "Drake" +recoup research deep "Tell me everything about Phoebe Bridgers — bio, streaming metrics, fan base, competitive landscape, and revenue opportunities" ``` See [`POST /api/research/deep`](/api-reference/research/deep).