{ "openapi": "3.1.0", "info": { "title": "Veezee API", "version": "2.1", "description": "LinkedIn data for AI agents: profiles, people search, companies, and posts, metered in credits with per-call receipts. Same contract as the MCP server at https://mcp.veezee.io/linkedin.", "contact": { "email": "hello@veezee.io", "url": "https://veezee.io" } }, "servers": [ { "url": "https://api.veezee.io" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/v1/linkedin/resolve-url": { "get": { "operationId": "resolveUrl", "summary": "Identify a LinkedIn URL", "description": "Identify what a LinkedIn URL points at before fetching it. Give any LinkedIn profile, company, or post URL (utm params, www/m subdomains, trailing slashes are fine); get back {type: person|company|post, id, handle, canonical_url}. For profile URLs, id is the stable person URN; for company URLs, id is the stable company URN; for post URLs, id is the activity URN extracted from the URL. For people, use the returned handle or id with linkedin_get_profile or linkedin_get_posts. For companies, use the returned HANDLE with linkedin_get_company or linkedin_get_posts; the company URN/id is a linkedin_search_people filter input, not a fetch identifier. Costs 2 credits. Skip this tool when you already have a slug, URN, or clean URL: linkedin_get_profile and linkedin_get_company accept those directly, so resolving first would waste 2 credits. Not for non-LinkedIn URLs; it returns INVALID_INPUT for those.", "x-platform": "linkedin", "x-input-examples": [ { "summary": "Profile URL from a user message", "value": { "url": "https://www.linkedin.com/in/williamhgates?utm_source=share" } }, { "summary": "Company URL", "value": { "url": "https://linkedin.com/company/anthropicresearch" } } ], "parameters": [ { "name": "url", "in": "query", "required": true, "schema": { "type": "string", "description": "A LinkedIn URL, e.g. https://www.linkedin.com/in/williamhgates or .../company/microsoft." } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required on paid-key calls; free-tier trial-key calls do not need it. Unique key per logical call (UUID recommended). Reuse the SAME key when retrying the same call; a replay returns the stored result without charging again. Reusing a key with different arguments returns IDEMPOTENCY_KEY_REUSED.", "schema": { "type": "string", "minLength": 8, "maxLength": 128 } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "url_resolution envelope (schema_version 2)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/url_resolution_envelope" } } } }, "400": { "description": "INVALID_INPUT | IDEMPOTENCY_KEY_REQUIRED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "UNAUTHORIZED | AUTH_REQUIRED | KEY_REQUIRED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "INSUFFICIENT_CREDITS | QUOTE_EXCEEDS_MAX_CREDITS", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "NOT_ENTITLED | TRIAL_CAP_EXCEEDED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "NOT_FOUND", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "IDEMPOTENCY_KEY_REUSED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "CONCURRENCY_LIMIT | RATE_LIMITED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "INTERNAL", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "502": { "description": "UPSTREAM_UNAVAILABLE", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "BUDGET_EXHAUSTED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/linkedin/profiles": { "get": { "operationId": "getProfile", "summary": "Get a LinkedIn person profile", "description": "Fetch one person's LinkedIn profile. identifier accepts a profile URL, the slug after /in/ (e.g. 'williamhgates'), or a urn:li:fsd_profile URN; URLs are cleaned automatically. Always returns the overview (name, headline, location, current position, follower counts) plus up to 2 requested sections from about|experience|education|skills at no extra cost; each section beyond 2 adds 2 credits (max 4 sections). Costs 4 credits base. If you only have a name, use linkedin_search_people first; this tool does not search. Results from linkedin_search_people with is_anonymous=true cannot be fetched here; treat them as 'someone matching this exists' and stop. Companies belong to linkedin_get_company.", "x-platform": "linkedin", "x-input-examples": [ { "summary": "By slug, overview only", "value": { "identifier": "williamhgates" } }, { "summary": "By URL with work history and education", "value": { "identifier": "https://www.linkedin.com/in/williamhgates", "sections": [ "experience", "education" ] } }, { "summary": "Live fetch by URN", "value": { "identifier": "urn:li:fsd_profile:ACoAAA8BYqEBCGLg_vT_ca6mMEqkpp9nVffJ3hc", "freshness": "realtime" } } ], "parameters": [ { "name": "identifier", "in": "query", "required": true, "schema": { "type": "string", "description": "Profile URL, slug (after /in/), or urn:li:fsd_profile URN." } }, { "name": "sections", "in": "query", "required": false, "style": "form", "explode": false, "schema": { "description": "Extra profile sections. First 2 are included in the base price.", "maxItems": 4, "type": "array", "items": { "type": "string", "enum": [ "about", "experience", "education", "skills" ] } } }, { "name": "freshness", "in": "query", "required": false, "schema": { "default": "recent", "description": "recent (default) serves cached data from the last few hours when available; realtime forces a live fetch for +2 credits (refunded if we fall back to cached data). Trial keys are cached-only and reject realtime with TRIAL_CAP_EXCEEDED; paying upgrades this same key to unlock it.", "type": "string", "enum": [ "recent", "realtime" ] } }, { "name": "max_credits", "in": "query", "required": false, "schema": { "description": "Spend ceiling for this one call. The call is rejected (nothing charged) if its quote exceeds this. Only the quote is ever reserved, never this ceiling.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required on paid-key calls; free-tier trial-key calls do not need it. Unique key per logical call (UUID recommended). Reuse the SAME key when retrying the same call; a replay returns the stored result without charging again. Reusing a key with different arguments returns IDEMPOTENCY_KEY_REUSED.", "schema": { "type": "string", "minLength": 8, "maxLength": 128 } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "person envelope (schema_version 2)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/person_envelope" } } } }, "400": { "description": "INVALID_INPUT | IDEMPOTENCY_KEY_REQUIRED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "UNAUTHORIZED | AUTH_REQUIRED | KEY_REQUIRED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "INSUFFICIENT_CREDITS | QUOTE_EXCEEDS_MAX_CREDITS", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "NOT_ENTITLED | TRIAL_CAP_EXCEEDED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "NOT_FOUND", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "IDEMPOTENCY_KEY_REUSED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "CONCURRENCY_LIMIT | RATE_LIMITED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "INTERNAL", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "502": { "description": "UPSTREAM_UNAVAILABLE", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "BUDGET_EXHAUSTED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/linkedin/search": { "get": { "operationId": "searchPeople", "summary": "Search people on LinkedIn", "description": "Find people on LinkedIn by keywords and filters. The right tool when you have a name, role, or 'who is the X at Y' question without a profile URL. Pass keywords (free text: name, title, or both) and any of first_name, last_name, title, school, current_company, past_company. If keywords is omitted it is derived from the name or title filters; school or company filters alone are rejected with INVALID_INPUT, so include keywords with those. Company filters accept a company name, slug, numeric id, or URN; names are resolved for you. Costs 10 credits including the first 10 results; each further 10 results add 1 credit (limit max 30; trial keys max 10). A cursor page is a NEW call priced the same way by its own limit, so one limit=30 call is much cheaper than three limit=10 pages; prefer a larger limit over paginating. Do NOT combine a company NAME filter with limit=30: name resolution spends one of the call's three internal fetches, so that combination is rejected. With a company name keep limit<=20; for limit=30 pass the company's numeric id or URN (linkedin_get_company returns both). Returns name, position, location, urn, public_identifier per result, a cursor for the next page, and total_matches. Results with is_anonymous=true are private profiles; do not pass them to linkedin_get_profile. For one known person with a URL/slug, call linkedin_get_profile directly instead.", "x-platform": "linkedin", "x-input-examples": [ { "summary": "Role at a company", "value": { "keywords": "CTO", "current_company": "anthropic" } }, { "summary": "Name search, more results", "value": { "keywords": "John Smith", "title": "software engineer", "limit": 30 } }, { "summary": "Next page", "value": { "keywords": "CTO", "current_company": "anthropic", "cursor": "" } } ], "parameters": [ { "name": "keywords", "in": "query", "required": false, "schema": { "description": "Free-text query: a name, a title, or both.", "type": "string" } }, { "name": "first_name", "in": "query", "required": false, "schema": { "description": "First-name filter, exact match.", "type": "string" } }, { "name": "last_name", "in": "query", "required": false, "schema": { "description": "Last-name filter, exact match.", "type": "string" } }, { "name": "title", "in": "query", "required": false, "schema": { "description": "Current job title filter.", "type": "string" } }, { "name": "school", "in": "query", "required": false, "schema": { "description": "School or university name filter.", "type": "string" } }, { "name": "current_company", "in": "query", "required": false, "schema": { "description": "Company name, slug, numeric id, or urn:li:fsd_company URN.", "type": "string" } }, { "name": "past_company", "in": "query", "required": false, "schema": { "description": "Same accepted forms as current_company.", "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "default": 10, "description": "How many results to return.", "type": "integer", "minimum": 1, "maximum": 30 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "description": "Cursor from a previous page.", "type": "string" } }, { "name": "freshness", "in": "query", "required": false, "schema": { "default": "recent", "description": "recent (default) serves cached data from the last few hours when available; realtime forces a live fetch for +2 credits (refunded if we fall back to cached data). Trial keys are cached-only and reject realtime with TRIAL_CAP_EXCEEDED; paying upgrades this same key to unlock it.", "type": "string", "enum": [ "recent", "realtime" ] } }, { "name": "max_credits", "in": "query", "required": false, "schema": { "description": "Spend ceiling for this one call. The call is rejected (nothing charged) if its quote exceeds this. Only the quote is ever reserved, never this ceiling.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required on paid-key calls; free-tier trial-key calls do not need it. Unique key per logical call (UUID recommended). Reuse the SAME key when retrying the same call; a replay returns the stored result without charging again. Reusing a key with different arguments returns IDEMPOTENCY_KEY_REUSED.", "schema": { "type": "string", "minLength": 8, "maxLength": 128 } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "people_search envelope (schema_version 2)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/people_search_envelope" } } } }, "400": { "description": "INVALID_INPUT | IDEMPOTENCY_KEY_REQUIRED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "UNAUTHORIZED | AUTH_REQUIRED | KEY_REQUIRED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "INSUFFICIENT_CREDITS | QUOTE_EXCEEDS_MAX_CREDITS", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "NOT_ENTITLED | TRIAL_CAP_EXCEEDED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "NOT_FOUND", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "IDEMPOTENCY_KEY_REUSED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "CONCURRENCY_LIMIT | RATE_LIMITED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "INTERNAL", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "502": { "description": "UPSTREAM_UNAVAILABLE", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "BUDGET_EXHAUSTED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/linkedin/companies": { "get": { "operationId": "getCompany", "summary": "Get a LinkedIn company", "description": "Fetch one company's LinkedIn page: name, description, industry, employee count, headquarters, website, founding year, specialities, and the URN/numeric id you need for linkedin_search_people company filters. identifier accepts a company URL, the slug after /company/ (e.g. 'microsoft'), or a website domain like 'microsoft.com'; numeric ids and URNs are search-filter inputs, not fetch identifiers. Domains are resolved to a company and verified against that company's website: a domain identifier always QUOTES base+4 credits (set max_credits accordingly), and the 4-credit resolution surcharge is refunded at settlement when the domain was resolved before, so known domains settle at the base price. A domain that cannot be verified to a company returns INVALID_INPUT with the closest matches instead of a guessed company. Costs 4 credits base. Do not guess a slug from a brand name: slugs are vanity strings and a famous name can belong to an unrelated company's page (linkedin.com/company/anthropic is a small investment fund, not the AI lab). When you only know the company's name, pass its website domain instead -- the verified form -- and sanity-check the returned industry and description against what you expected. This tool does not search by name: if you only have an approximate company name, use linkedin_search_people's current_company filter with keywords (the filter resolves names) or give the exact slug. For the company's posts, use linkedin_get_posts with the same identifier (URL, slug, or website domain all work there too).", "x-platform": "linkedin", "x-input-examples": [ { "summary": "By slug", "value": { "identifier": "microsoft" } }, { "summary": "By website domain", "value": { "identifier": "microsoft.com" } }, { "summary": "By URL, live", "value": { "identifier": "https://www.linkedin.com/company/anthropicresearch/", "freshness": "realtime" } } ], "parameters": [ { "name": "identifier", "in": "query", "required": true, "schema": { "type": "string", "description": "Company URL, slug (after /company/), or website domain (e.g. 'microsoft.com'). Numeric ids/URNs are not fetchable; use them only in linkedin_search_people company filters." } }, { "name": "freshness", "in": "query", "required": false, "schema": { "default": "recent", "description": "recent (default) serves cached data from the last few hours when available; realtime forces a live fetch for +2 credits (refunded if we fall back to cached data). Trial keys are cached-only and reject realtime with TRIAL_CAP_EXCEEDED; paying upgrades this same key to unlock it.", "type": "string", "enum": [ "recent", "realtime" ] } }, { "name": "max_credits", "in": "query", "required": false, "schema": { "description": "Spend ceiling for this one call. The call is rejected (nothing charged) if its quote exceeds this. Only the quote is ever reserved, never this ceiling.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required on paid-key calls; free-tier trial-key calls do not need it. Unique key per logical call (UUID recommended). Reuse the SAME key when retrying the same call; a replay returns the stored result without charging again. Reusing a key with different arguments returns IDEMPOTENCY_KEY_REUSED.", "schema": { "type": "string", "minLength": 8, "maxLength": 128 } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "company envelope (schema_version 2)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/company_envelope" } } } }, "400": { "description": "INVALID_INPUT | IDEMPOTENCY_KEY_REQUIRED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "UNAUTHORIZED | AUTH_REQUIRED | KEY_REQUIRED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "INSUFFICIENT_CREDITS | QUOTE_EXCEEDS_MAX_CREDITS", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "NOT_ENTITLED | TRIAL_CAP_EXCEEDED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "NOT_FOUND", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "IDEMPOTENCY_KEY_REUSED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "CONCURRENCY_LIMIT | RATE_LIMITED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "INTERNAL", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "502": { "description": "UPSTREAM_UNAVAILABLE", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "BUDGET_EXHAUSTED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/linkedin/posts": { "get": { "operationId": "getPosts", "summary": "Get recent posts by a person or company", "description": "Fetch the recent LinkedIn posts of one person or one company. identifier accepts a profile or company URL, a slug, a person URN, or a company website domain like 'microsoft.com'; the entity type is detected automatically. A domain resolves to its verified company first, exactly like linkedin_get_company: it QUOTES base+4 credits (set max_credits accordingly) and the surcharge is refunded at settlement for already-known domains, so they settle at the base price. Company URNs and numeric company ids are search-filter inputs, not fetch identifiers: use the company slug, URL, or domain here. Returns one page of posts (text, created_at, author, likes, comments_count, shares, is_repost, url) with a cursor for older posts. Costs 4 credits per page. Use this for 'what has X been posting', voice-of-company research, or activity checks before outreach. Not for reading one specific post you already have a URL for, and not for keyword search across LinkedIn; neither is supported in v1.", "x-platform": "linkedin", "x-input-examples": [ { "summary": "Company posts", "value": { "identifier": "https://www.linkedin.com/company/microsoft/" } }, { "summary": "Company posts by website domain", "value": { "identifier": "microsoft.com" } }, { "summary": "Person's posts by slug", "value": { "identifier": "williamhgates" } } ], "parameters": [ { "name": "identifier", "in": "query", "required": true, "schema": { "type": "string", "description": "Person or company URL, slug, URN, or company website domain." } }, { "name": "cursor", "in": "query", "required": false, "schema": { "description": "Cursor from a previous page for older posts.", "type": "string" } }, { "name": "freshness", "in": "query", "required": false, "schema": { "default": "recent", "description": "recent (default) serves cached data from the last few hours when available; realtime forces a live fetch for +2 credits (refunded if we fall back to cached data). Trial keys are cached-only and reject realtime with TRIAL_CAP_EXCEEDED; paying upgrades this same key to unlock it.", "type": "string", "enum": [ "recent", "realtime" ] } }, { "name": "max_credits", "in": "query", "required": false, "schema": { "description": "Spend ceiling for this one call. The call is rejected (nothing charged) if its quote exceeds this. Only the quote is ever reserved, never this ceiling.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required on paid-key calls; free-tier trial-key calls do not need it. Unique key per logical call (UUID recommended). Reuse the SAME key when retrying the same call; a replay returns the stored result without charging again. Reusing a key with different arguments returns IDEMPOTENCY_KEY_REUSED.", "schema": { "type": "string", "minLength": 8, "maxLength": 128 } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "posts envelope (schema_version 2)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/posts_envelope" } } } }, "400": { "description": "INVALID_INPUT | IDEMPOTENCY_KEY_REQUIRED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "UNAUTHORIZED | AUTH_REQUIRED | KEY_REQUIRED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "INSUFFICIENT_CREDITS | QUOTE_EXCEEDS_MAX_CREDITS", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "NOT_ENTITLED | TRIAL_CAP_EXCEEDED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "NOT_FOUND", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "IDEMPOTENCY_KEY_REUSED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "CONCURRENCY_LIMIT | RATE_LIMITED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "INTERNAL", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "502": { "description": "UPSTREAM_UNAVAILABLE", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "BUDGET_EXHAUSTED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/reddit/search": { "get": { "operationId": "redditSearch", "summary": "Search Reddit posts, comments, subreddits, or users", "description": "Search all of Reddit by keywords. type picks the target: posts (default), comments (what people actually say about a product, problem, or brand -- unique to Reddit search), subreddits (find communities), users. Pass query as free text up to 256 characters; decompose broad topics into several narrower queries, since result depth per query is capped upstream around a few hundred results. sort applies to posts (relevance|top|new|hot|comment_count) and comments (relevance|top|new); range (past_hour..all_time) applies to posts only; both are rejected with INVALID_INPUT elsewhere. Costs 6 credits per page; a cursor page is a NEW call priced the same way. Returns one page of summaries (author, title or comment text, upvotes, comment_count, created_at, permalink, id) with a cursor; there is no server-side time window on comment search, so for monitoring filter on created_at yourself and poll with sort=new. Fetch full post bodies and discussion threads with reddit_get_post; read one community's feed with reddit_get_subreddit_posts. For high-volume recency sweeps across X instead, use x_search.", "x-platform": "reddit", "x-input-examples": [ { "summary": "What do people say about a product", "value": { "query": "notion alternative", "type": "comments" } }, { "summary": "Fresh posts about a topic this week", "value": { "query": "local llm inference", "type": "posts", "sort": "new", "range": "past_week" } }, { "summary": "Next page of a sweep", "value": { "query": "notion alternative", "type": "comments", "cursor": "eyJwYWdlIjoyfQ" } } ], "parameters": [ { "name": "query", "in": "query", "required": true, "schema": { "type": "string", "maxLength": 256, "description": "Free-text keywords, e.g. 'self hosted photo backup'. Not a URL; use reddit_resolve_url for URLs." } }, { "name": "type", "in": "query", "required": false, "schema": { "default": "posts", "description": "What to search. 'comments' finds mentions inside discussions; 'subreddits' finds communities.", "type": "string", "enum": [ "posts", "comments", "subreddits", "users" ] } }, { "name": "sort", "in": "query", "required": false, "schema": { "description": "posts: any value; comments: relevance|top|new; invalid for subreddits and users.", "type": "string", "enum": [ "relevance", "top", "new", "hot", "comment_count" ] } }, { "name": "range", "in": "query", "required": false, "schema": { "description": "Time window. posts only.", "type": "string", "enum": [ "past_hour", "today", "past_week", "past_month", "past_year", "all_time" ] } }, { "name": "cursor", "in": "query", "required": false, "schema": { "description": "Cursor from a previous page.", "type": "string" } }, { "name": "freshness", "in": "query", "required": false, "schema": { "default": "recent", "description": "recent (default) serves cached data from the last few hours when available; realtime forces a live fetch for +2 credits (refunded if we fall back to cached data). Trial keys are cached-only and reject realtime with TRIAL_CAP_EXCEEDED; paying upgrades this same key to unlock it.", "type": "string", "enum": [ "recent", "realtime" ] } }, { "name": "max_credits", "in": "query", "required": false, "schema": { "description": "Spend ceiling for this one call. The call is rejected (nothing charged) if its quote exceeds this. Only the quote is ever reserved, never this ceiling.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required on paid-key calls; free-tier trial-key calls do not need it. Unique key per logical call (UUID recommended). Reuse the SAME key when retrying the same call; a replay returns the stored result without charging again. Reusing a key with different arguments returns IDEMPOTENCY_KEY_REUSED.", "schema": { "type": "string", "minLength": 8, "maxLength": 128 } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "reddit_search envelope (schema_version 2)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reddit_search_envelope" } } } }, "400": { "description": "INVALID_INPUT | IDEMPOTENCY_KEY_REQUIRED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "UNAUTHORIZED | AUTH_REQUIRED | KEY_REQUIRED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "INSUFFICIENT_CREDITS | QUOTE_EXCEEDS_MAX_CREDITS", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "NOT_ENTITLED | TRIAL_CAP_EXCEEDED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "NOT_FOUND", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "IDEMPOTENCY_KEY_REUSED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "CONCURRENCY_LIMIT | RATE_LIMITED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "INTERNAL", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "502": { "description": "UPSTREAM_UNAVAILABLE", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "BUDGET_EXHAUSTED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/reddit/subreddits": { "get": { "operationId": "getSubreddit", "summary": "Get subreddit details", "description": "Fetch one subreddit's profile: title, description, subscriber and active-user counts, age, NSFW flag, and topics. subreddit_name is the name without the r/ prefix, e.g. 'selfhosted'; a full reddit.com URL also works. Set include_settings to also get the community rules and moderator list for +2 credits (useful before posting or judging moderation culture). Costs 4 credits base. Subscriber counts here are the standard sizing signal for market research. This tool does not return posts: read the feed with reddit_get_subreddit_posts, and discover subreddits you don't know by name with reddit_search type=subreddits.", "x-platform": "reddit", "x-input-examples": [ { "summary": "Size up a community", "value": { "subreddit_name": "selfhosted" } }, { "summary": "Rules and moderators before engaging", "value": { "subreddit_name": "programming", "include_settings": true } } ], "parameters": [ { "name": "subreddit_name", "in": "query", "required": true, "schema": { "type": "string", "description": "Subreddit name without the r/ prefix, e.g. 'selfhosted'. Full URLs are accepted and cleaned." } }, { "name": "include_settings", "in": "query", "required": false, "schema": { "default": false, "description": "Also return rules and moderators for +2 credits.", "type": "boolean" } }, { "name": "freshness", "in": "query", "required": false, "schema": { "default": "recent", "description": "recent (default) serves cached data from the last few hours when available; realtime forces a live fetch for +2 credits (refunded if we fall back to cached data). Trial keys are cached-only and reject realtime with TRIAL_CAP_EXCEEDED; paying upgrades this same key to unlock it.", "type": "string", "enum": [ "recent", "realtime" ] } }, { "name": "max_credits", "in": "query", "required": false, "schema": { "description": "Spend ceiling for this one call. The call is rejected (nothing charged) if its quote exceeds this. Only the quote is ever reserved, never this ceiling.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required on paid-key calls; free-tier trial-key calls do not need it. Unique key per logical call (UUID recommended). Reuse the SAME key when retrying the same call; a replay returns the stored result without charging again. Reusing a key with different arguments returns IDEMPOTENCY_KEY_REUSED.", "schema": { "type": "string", "minLength": 8, "maxLength": 128 } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "subreddit envelope (schema_version 2)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/subreddit_envelope" } } } }, "400": { "description": "INVALID_INPUT | IDEMPOTENCY_KEY_REQUIRED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "UNAUTHORIZED | AUTH_REQUIRED | KEY_REQUIRED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "INSUFFICIENT_CREDITS | QUOTE_EXCEEDS_MAX_CREDITS", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "NOT_ENTITLED | TRIAL_CAP_EXCEEDED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "NOT_FOUND", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "IDEMPOTENCY_KEY_REUSED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "CONCURRENCY_LIMIT | RATE_LIMITED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "INTERNAL", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "502": { "description": "UPSTREAM_UNAVAILABLE", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "BUDGET_EXHAUSTED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/reddit/subreddit-posts": { "get": { "operationId": "getSubredditPosts", "summary": "Get a subreddit's posts", "description": "Fetch one page of posts from a single subreddit, the community-monitoring primitive. subreddit_name is the name without the r/ prefix. sort defaults to the subreddit's own front-page order (best); use sort=new for monitoring. sort=top and controversial need a range, but the window is currently not applied upstream on this feed: top returns the subreddit's all-time top posts whatever range says (time-windowed tops are a known gap here; reddit_search's range DOES work for keyword queries). Costs 4 credits per page; a cursor page is a NEW call priced the same way. Reddit splices about one promoted ad into every feed page; these are dropped by default, so set include_promoted=true only when ads ARE the data you want (ad intelligence, who targets this community) -- kept ads carry is_promoted=true. Returns post summaries (title, author, upvotes, comment_count, created_at, permalink, id) with a cursor for older posts; bodies and discussions come from reddit_get_post with the returned ids. For keyword search across all of Reddit use reddit_search; this tool takes no query.", "x-platform": "reddit", "x-input-examples": [ { "summary": "Monitor a community for new posts", "value": { "subreddit_name": "selfhosted", "sort": "new" } }, { "summary": "All-time top posts", "value": { "subreddit_name": "programming", "sort": "top", "range": "all_time" } }, { "summary": "Ad intelligence: who advertises to this community", "value": { "subreddit_name": "programming", "include_promoted": true } } ], "parameters": [ { "name": "subreddit_name", "in": "query", "required": true, "schema": { "type": "string", "description": "Subreddit name without the r/ prefix, e.g. 'selfhosted'." } }, { "name": "sort", "in": "query", "required": false, "schema": { "description": "Defaults to the subreddit's front-page order.", "type": "string", "enum": [ "best", "hot", "new", "top", "controversial", "rising" ] } }, { "name": "range", "in": "query", "required": false, "schema": { "description": "Required with sort=top or controversial, but currently not applied upstream on this feed (results are all-time).", "type": "string", "enum": [ "past_hour", "today", "past_week", "past_month", "past_year", "all_time" ] } }, { "name": "include_promoted", "in": "query", "required": false, "schema": { "default": false, "description": "Keep the promoted ads Reddit splices into the feed (marked is_promoted). Default drops them.", "type": "boolean" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "description": "Cursor from a previous page for older posts.", "type": "string" } }, { "name": "freshness", "in": "query", "required": false, "schema": { "default": "recent", "description": "recent (default) serves cached data from the last few hours when available; realtime forces a live fetch for +2 credits (refunded if we fall back to cached data). Trial keys are cached-only and reject realtime with TRIAL_CAP_EXCEEDED; paying upgrades this same key to unlock it.", "type": "string", "enum": [ "recent", "realtime" ] } }, { "name": "max_credits", "in": "query", "required": false, "schema": { "description": "Spend ceiling for this one call. The call is rejected (nothing charged) if its quote exceeds this. Only the quote is ever reserved, never this ceiling.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required on paid-key calls; free-tier trial-key calls do not need it. Unique key per logical call (UUID recommended). Reuse the SAME key when retrying the same call; a replay returns the stored result without charging again. Reusing a key with different arguments returns IDEMPOTENCY_KEY_REUSED.", "schema": { "type": "string", "minLength": 8, "maxLength": 128 } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "reddit_posts envelope (schema_version 2)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reddit_posts_envelope" } } } }, "400": { "description": "INVALID_INPUT | IDEMPOTENCY_KEY_REQUIRED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "UNAUTHORIZED | AUTH_REQUIRED | KEY_REQUIRED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "INSUFFICIENT_CREDITS | QUOTE_EXCEEDS_MAX_CREDITS", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "NOT_ENTITLED | TRIAL_CAP_EXCEEDED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "NOT_FOUND", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "IDEMPOTENCY_KEY_REUSED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "CONCURRENCY_LIMIT | RATE_LIMITED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "INTERNAL", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "502": { "description": "UPSTREAM_UNAVAILABLE", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "BUDGET_EXHAUSTED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/reddit/users": { "get": { "operationId": "getRedditUser", "summary": "Get a Reddit user", "description": "Fetch one Reddit user's public profile: username, account age, karma, follower count, and description. username is the name without the u/ prefix, e.g. 'spez'; a full profile URL also works. Add up to 2 sections from comments|posts|subreddits at 2 credits each: comments and posts return that user's recent activity (first page), subreddits returns where they are active. Costs 4 credits base. Use this to profile loud voices found via reddit_search before quoting or engaging them. To find users by topic, use reddit_search type=users; this tool needs an exact username.", "x-platform": "reddit", "x-input-examples": [ { "summary": "Profile overview", "value": { "username": "spez" } }, { "summary": "With recent comments and where they post", "value": { "username": "spez", "sections": [ "comments", "subreddits" ] } } ], "parameters": [ { "name": "username", "in": "query", "required": true, "schema": { "type": "string", "description": "Reddit username without the u/ prefix, e.g. 'spez'. Full profile URLs are accepted and cleaned." } }, { "name": "sections", "in": "query", "required": false, "style": "form", "explode": false, "schema": { "description": "Extra activity sections, 2 credits each (max 2 per call).", "maxItems": 2, "type": "array", "items": { "type": "string", "enum": [ "comments", "posts", "subreddits" ] } } }, { "name": "freshness", "in": "query", "required": false, "schema": { "default": "recent", "description": "recent (default) serves cached data from the last few hours when available; realtime forces a live fetch for +2 credits (refunded if we fall back to cached data). Trial keys are cached-only and reject realtime with TRIAL_CAP_EXCEEDED; paying upgrades this same key to unlock it.", "type": "string", "enum": [ "recent", "realtime" ] } }, { "name": "max_credits", "in": "query", "required": false, "schema": { "description": "Spend ceiling for this one call. The call is rejected (nothing charged) if its quote exceeds this. Only the quote is ever reserved, never this ceiling.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required on paid-key calls; free-tier trial-key calls do not need it. Unique key per logical call (UUID recommended). Reuse the SAME key when retrying the same call; a replay returns the stored result without charging again. Reusing a key with different arguments returns IDEMPOTENCY_KEY_REUSED.", "schema": { "type": "string", "minLength": 8, "maxLength": 128 } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "reddit_user envelope (schema_version 2)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reddit_user_envelope" } } } }, "400": { "description": "INVALID_INPUT | IDEMPOTENCY_KEY_REQUIRED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "UNAUTHORIZED | AUTH_REQUIRED | KEY_REQUIRED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "INSUFFICIENT_CREDITS | QUOTE_EXCEEDS_MAX_CREDITS", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "NOT_ENTITLED | TRIAL_CAP_EXCEEDED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "NOT_FOUND", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "IDEMPOTENCY_KEY_REUSED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "CONCURRENCY_LIMIT | RATE_LIMITED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "INTERNAL", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "502": { "description": "UPSTREAM_UNAVAILABLE", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "BUDGET_EXHAUSTED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/reddit/posts": { "get": { "operationId": "getRedditPost", "summary": "Get Reddit posts by id, with optional discussion thread", "description": "Fetch full post content for up to 100 Reddit posts by their t3_ ids in one call -- the follow-up loop after reddit_search or reddit_get_subreddit_posts. Costs 4 credits for up to 10 ids, +1 credit per further 10 ids; every post comes back with its full body text. With exactly ONE id you may set detail to 'full' for +4 credits to also get the discussion tree (comments flattened in tree order with depth, about 200 per page, with a comments_cursor to continue), or pass comment_id (a t1_ id, also +4 credits) to fetch one specific comment in its post context. Post ids come from the other Reddit tools or from reddit_resolve_url on a post URL. Not for discovering posts; search first, then batch-fetch here.", "x-platform": "reddit", "x-input-examples": [ { "summary": "Batch-fetch bodies for search hits", "value": { "post_ids": [ "t3_1tbups6", "t3_1tbuneg" ] } }, { "summary": "One post with its discussion", "value": { "post_ids": [ "t3_1tbups6" ], "detail": "full", "sort": "top" } } ], "parameters": [ { "name": "post_ids", "in": "query", "required": true, "style": "form", "explode": false, "schema": { "minItems": 1, "maxItems": 100, "type": "array", "items": { "type": "string" }, "description": "1 to 100 post ids with the t3_ prefix, e.g. [\"t3_1tbups6\"]." } }, { "name": "detail", "in": "query", "required": false, "schema": { "default": "concise", "description": "'full' adds the discussion tree; only valid with exactly one id, +4 credits.", "type": "string", "enum": [ "concise", "full" ] } }, { "name": "comment_id", "in": "query", "required": false, "schema": { "description": "A t1_ comment id to fetch in context; only valid with exactly one post id, +4 credits like detail 'full'.", "type": "string" } }, { "name": "sort", "in": "query", "required": false, "schema": { "description": "Discussion-tree order; only with detail 'full'.", "type": "string", "enum": [ "best", "new", "top", "controversial", "old", "qa" ] } }, { "name": "cursor", "in": "query", "required": false, "schema": { "description": "comments_cursor from a previous detail='full' page.", "type": "string" } }, { "name": "freshness", "in": "query", "required": false, "schema": { "default": "recent", "description": "recent (default) serves cached data from the last few hours when available; realtime forces a live fetch for +2 credits (refunded if we fall back to cached data). Trial keys are cached-only and reject realtime with TRIAL_CAP_EXCEEDED; paying upgrades this same key to unlock it.", "type": "string", "enum": [ "recent", "realtime" ] } }, { "name": "max_credits", "in": "query", "required": false, "schema": { "description": "Spend ceiling for this one call. The call is rejected (nothing charged) if its quote exceeds this. Only the quote is ever reserved, never this ceiling.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required on paid-key calls; free-tier trial-key calls do not need it. Unique key per logical call (UUID recommended). Reuse the SAME key when retrying the same call; a replay returns the stored result without charging again. Reusing a key with different arguments returns IDEMPOTENCY_KEY_REUSED.", "schema": { "type": "string", "minLength": 8, "maxLength": 128 } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "reddit_thread envelope (schema_version 2)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/reddit_thread_envelope" } } } }, "400": { "description": "INVALID_INPUT | IDEMPOTENCY_KEY_REQUIRED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "UNAUTHORIZED | AUTH_REQUIRED | KEY_REQUIRED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "INSUFFICIENT_CREDITS | QUOTE_EXCEEDS_MAX_CREDITS", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "NOT_ENTITLED | TRIAL_CAP_EXCEEDED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "NOT_FOUND", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "IDEMPOTENCY_KEY_REUSED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "CONCURRENCY_LIMIT | RATE_LIMITED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "INTERNAL", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "502": { "description": "UPSTREAM_UNAVAILABLE", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "BUDGET_EXHAUSTED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/reddit/resolve-url": { "get": { "operationId": "redditResolveUrl", "summary": "Identify a Reddit URL", "description": "Identify what a Reddit URL points at before fetching it. Give any reddit.com or redd.it URL (share links, old.reddit.com, trailing params are fine); get back {type: subreddit|user|post|comment, id, handle, canonical_url}. Post URLs yield the t3_ id for reddit_get_post; comment permalinks yield the t1_ id; subreddit and user URLs yield the name for reddit_get_subreddit or reddit_get_user. Costs 2 credits and parses offline without fetching the page. Skip this tool when you already have a t3_/t1_ id, subreddit name, or username: the other Reddit tools accept those directly. Not for non-Reddit URLs; it returns INVALID_INPUT for those.", "x-platform": "reddit", "x-input-examples": [ { "summary": "Post share link", "value": { "url": "https://redd.it/1tbups6" } }, { "summary": "Comment permalink", "value": { "url": "https://www.reddit.com/r/programming/comments/1tbups6/comment/okpklb6/" } } ], "parameters": [ { "name": "url", "in": "query", "required": true, "schema": { "type": "string", "description": "A Reddit URL, e.g. https://www.reddit.com/r/selfhosted/comments/1tbups6/... or https://redd.it/1tbups6." } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required on paid-key calls; free-tier trial-key calls do not need it. Unique key per logical call (UUID recommended). Reuse the SAME key when retrying the same call; a replay returns the stored result without charging again. Reusing a key with different arguments returns IDEMPOTENCY_KEY_REUSED.", "schema": { "type": "string", "minLength": 8, "maxLength": 128 } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "url_resolution envelope (schema_version 2)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/url_resolution_envelope" } } } }, "400": { "description": "INVALID_INPUT | IDEMPOTENCY_KEY_REQUIRED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "UNAUTHORIZED | AUTH_REQUIRED | KEY_REQUIRED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "INSUFFICIENT_CREDITS | QUOTE_EXCEEDS_MAX_CREDITS", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "NOT_ENTITLED | TRIAL_CAP_EXCEEDED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "NOT_FOUND", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "IDEMPOTENCY_KEY_REUSED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "CONCURRENCY_LIMIT | RATE_LIMITED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "INTERNAL", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "502": { "description": "UPSTREAM_UNAVAILABLE", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "BUDGET_EXHAUSTED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/x/search": { "get": { "operationId": "xSearch", "summary": "Search X (formerly Twitter)", "description": "Search X by keywords. type picks the mode: recent (default) is the deep chronological sweep and keeps paginating as far as you follow the cursor; popular returns the highest-engagement tweets for the query; people finds accounts and returns a single page (no cursor). Advanced query operators pass through verbatim, e.g. \"from:nasa\", \"min_faves:100\", exact phrases in quotes -- there is no separate date parameter, so use since:/until: operators for time windows. Costs 6 credits per page; a cursor page is a NEW call priced the same way, so a deep sweep costs linearly in pages. Returns tweet summaries (text, author with follower count, views, likes, retweets, replies, created_at, url, id) with a cursor. Fetch one tweet's full detail with x_get_tweet and an account's timeline with x_get_tweets. For comment-level sentiment inside topic communities, reddit_search type=comments is usually the sharper instrument.", "x-platform": "x", "x-input-examples": [ { "summary": "Fresh mentions of a product", "value": { "query": "veezee api" } }, { "summary": "Highest-engagement takes on a topic", "value": { "query": "ai agents data access", "type": "popular" } }, { "summary": "Find accounts", "value": { "query": "developer relations ai", "type": "people" } } ], "parameters": [ { "name": "query", "in": "query", "required": true, "schema": { "type": "string", "description": "Free-text keywords; X advanced operators work, e.g. 'claude code from:AnthropicAI since:2026-06-01'." } }, { "name": "type", "in": "query", "required": false, "schema": { "default": "recent", "description": "recent = chronological deep sweep; popular = top engagement; people = account search (single page).", "type": "string", "enum": [ "recent", "popular", "people" ] } }, { "name": "cursor", "in": "query", "required": false, "schema": { "description": "Cursor from a previous page. Not valid with type 'people'.", "type": "string" } }, { "name": "freshness", "in": "query", "required": false, "schema": { "default": "recent", "description": "recent (default) serves cached data from the last few hours when available; realtime forces a live fetch for +2 credits (refunded if we fall back to cached data). Trial keys are cached-only and reject realtime with TRIAL_CAP_EXCEEDED; paying upgrades this same key to unlock it.", "type": "string", "enum": [ "recent", "realtime" ] } }, { "name": "max_credits", "in": "query", "required": false, "schema": { "description": "Spend ceiling for this one call. The call is rejected (nothing charged) if its quote exceeds this. Only the quote is ever reserved, never this ceiling.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required on paid-key calls; free-tier trial-key calls do not need it. Unique key per logical call (UUID recommended). Reuse the SAME key when retrying the same call; a replay returns the stored result without charging again. Reusing a key with different arguments returns IDEMPOTENCY_KEY_REUSED.", "schema": { "type": "string", "minLength": 8, "maxLength": 128 } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "x_search envelope (schema_version 2)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/x_search_envelope" } } } }, "400": { "description": "INVALID_INPUT | IDEMPOTENCY_KEY_REQUIRED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "UNAUTHORIZED | AUTH_REQUIRED | KEY_REQUIRED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "INSUFFICIENT_CREDITS | QUOTE_EXCEEDS_MAX_CREDITS", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "NOT_ENTITLED | TRIAL_CAP_EXCEEDED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "NOT_FOUND", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "IDEMPOTENCY_KEY_REUSED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "CONCURRENCY_LIMIT | RATE_LIMITED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "INTERNAL", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "502": { "description": "UPSTREAM_UNAVAILABLE", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "BUDGET_EXHAUSTED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/x/profiles": { "get": { "operationId": "getXProfile", "summary": "Get an X profile", "description": "Fetch one X account's profile: name, bio, location, website, follower/following counts, tweet and media counts, verification state, and join date. identifier accepts a screen name without the @ (e.g. 'nasa'), a full x.com or twitter.com profile URL, or the numeric account id; numeric strings are treated as ids, and the rare all-digit handle can be forced with by='screen_name'. Costs 4 credits. The returned platform_fields.id is stable across handle changes; store it for repeat lookups. To find accounts by topic use x_search type=people, and to read what an account posts use x_get_tweets; this tool returns no tweets.", "x-platform": "x", "x-input-examples": [ { "summary": "By handle", "value": { "identifier": "nasa" } }, { "summary": "By stable numeric id", "value": { "identifier": "11348282", "by": "id" } } ], "parameters": [ { "name": "identifier", "in": "query", "required": true, "schema": { "type": "string", "description": "Screen name without the @ (e.g. 'nasa'), profile URL, or numeric account id." } }, { "name": "by", "in": "query", "required": false, "schema": { "description": "Force how identifier is interpreted; auto-detected when omitted.", "type": "string", "enum": [ "screen_name", "id" ] } }, { "name": "freshness", "in": "query", "required": false, "schema": { "default": "recent", "description": "recent (default) serves cached data from the last few hours when available; realtime forces a live fetch for +2 credits (refunded if we fall back to cached data). Trial keys are cached-only and reject realtime with TRIAL_CAP_EXCEEDED; paying upgrades this same key to unlock it.", "type": "string", "enum": [ "recent", "realtime" ] } }, { "name": "max_credits", "in": "query", "required": false, "schema": { "description": "Spend ceiling for this one call. The call is rejected (nothing charged) if its quote exceeds this. Only the quote is ever reserved, never this ceiling.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required on paid-key calls; free-tier trial-key calls do not need it. Unique key per logical call (UUID recommended). Reuse the SAME key when retrying the same call; a replay returns the stored result without charging again. Reusing a key with different arguments returns IDEMPOTENCY_KEY_REUSED.", "schema": { "type": "string", "minLength": 8, "maxLength": 128 } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "x_profile envelope (schema_version 2)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/x_profile_envelope" } } } }, "400": { "description": "INVALID_INPUT | IDEMPOTENCY_KEY_REQUIRED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "UNAUTHORIZED | AUTH_REQUIRED | KEY_REQUIRED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "INSUFFICIENT_CREDITS | QUOTE_EXCEEDS_MAX_CREDITS", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "NOT_ENTITLED | TRIAL_CAP_EXCEEDED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "NOT_FOUND", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "IDEMPOTENCY_KEY_REUSED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "CONCURRENCY_LIMIT | RATE_LIMITED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "INTERNAL", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "502": { "description": "UPSTREAM_UNAVAILABLE", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "BUDGET_EXHAUSTED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/x/tweets": { "get": { "operationId": "getXTweets", "summary": "Get an account's tweets", "description": "Fetch one page of an X account's timeline. identifier is a screen name, profile URL, or numeric id (auto-detected). mode picks the view: posts (default) is the account's own tweets, posts_and_replies includes their replies, highlights is the account's pinned highlights tab. include_retweets (default true) filters retweets out when false. Costs 4 credits per page; a cursor page is a NEW call priced the same way. Returns tweet summaries with engagement counts and a cursor for older tweets. Use this for 'what has X been posting', voice checks before outreach, or drafting replies in an account's register. For keyword search across all of X use x_search; for one specific tweet you already have, x_get_tweet.", "x-platform": "x", "x-input-examples": [ { "summary": "Recent tweets", "value": { "identifier": "nasa" } }, { "summary": "Including replies, no retweets", "value": { "identifier": "nasa", "mode": "posts_and_replies", "include_retweets": false } } ], "parameters": [ { "name": "identifier", "in": "query", "required": true, "schema": { "type": "string", "description": "Screen name without the @, profile URL, or numeric account id." } }, { "name": "mode", "in": "query", "required": false, "schema": { "default": "posts", "description": "Which timeline view to read.", "type": "string", "enum": [ "posts", "posts_and_replies", "highlights" ] } }, { "name": "include_retweets", "in": "query", "required": false, "schema": { "default": true, "description": "Set false to drop retweets from the page.", "type": "boolean" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "description": "Cursor from a previous page for older tweets.", "type": "string" } }, { "name": "freshness", "in": "query", "required": false, "schema": { "default": "recent", "description": "recent (default) serves cached data from the last few hours when available; realtime forces a live fetch for +2 credits (refunded if we fall back to cached data). Trial keys are cached-only and reject realtime with TRIAL_CAP_EXCEEDED; paying upgrades this same key to unlock it.", "type": "string", "enum": [ "recent", "realtime" ] } }, { "name": "max_credits", "in": "query", "required": false, "schema": { "description": "Spend ceiling for this one call. The call is rejected (nothing charged) if its quote exceeds this. Only the quote is ever reserved, never this ceiling.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required on paid-key calls; free-tier trial-key calls do not need it. Unique key per logical call (UUID recommended). Reuse the SAME key when retrying the same call; a replay returns the stored result without charging again. Reusing a key with different arguments returns IDEMPOTENCY_KEY_REUSED.", "schema": { "type": "string", "minLength": 8, "maxLength": 128 } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "x_tweets envelope (schema_version 2)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/x_tweets_envelope" } } } }, "400": { "description": "INVALID_INPUT | IDEMPOTENCY_KEY_REQUIRED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "UNAUTHORIZED | AUTH_REQUIRED | KEY_REQUIRED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "INSUFFICIENT_CREDITS | QUOTE_EXCEEDS_MAX_CREDITS", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "NOT_ENTITLED | TRIAL_CAP_EXCEEDED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "NOT_FOUND", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "IDEMPOTENCY_KEY_REUSED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "CONCURRENCY_LIMIT | RATE_LIMITED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "INTERNAL", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "502": { "description": "UPSTREAM_UNAVAILABLE", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "BUDGET_EXHAUSTED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/x/tweet": { "get": { "operationId": "getXTweet", "summary": "Get one tweet with full metrics", "description": "Fetch one tweet by id with full engagement metrics: views, likes, retweets, quotes, replies, bookmarks, language, and the quoted tweet inline when there is one. tweet_id is the numeric id from a tweet URL (the digits after /status/) or from any other X tool's results; full tweet URLs are accepted too. Costs 4 credits. Use this to verify engagement before citing a tweet or to read a quoted thread hop by hop. It returns a single tweet, not the conversation around it: for the author's other tweets use x_get_tweets, and to find tweets by topic use x_search.", "x-platform": "x", "x-input-examples": [ { "summary": "By id from search results", "value": { "tweet_id": "2054497961162478079" } }, { "summary": "By URL", "value": { "tweet_id": "https://x.com/nasa/status/2054497961162478079" } } ], "parameters": [ { "name": "tweet_id", "in": "query", "required": true, "schema": { "type": "string", "description": "Numeric tweet id, e.g. '2054497961162478079', or a full tweet URL." } }, { "name": "freshness", "in": "query", "required": false, "schema": { "default": "recent", "description": "recent (default) serves cached data from the last few hours when available; realtime forces a live fetch for +2 credits (refunded if we fall back to cached data). Trial keys are cached-only and reject realtime with TRIAL_CAP_EXCEEDED; paying upgrades this same key to unlock it.", "type": "string", "enum": [ "recent", "realtime" ] } }, { "name": "max_credits", "in": "query", "required": false, "schema": { "description": "Spend ceiling for this one call. The call is rejected (nothing charged) if its quote exceeds this. Only the quote is ever reserved, never this ceiling.", "type": "integer", "minimum": 0, "maximum": 9007199254740991 } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required on paid-key calls; free-tier trial-key calls do not need it. Unique key per logical call (UUID recommended). Reuse the SAME key when retrying the same call; a replay returns the stored result without charging again. Reusing a key with different arguments returns IDEMPOTENCY_KEY_REUSED.", "schema": { "type": "string", "minLength": 8, "maxLength": 128 } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "x_tweet envelope (schema_version 2)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/x_tweet_envelope" } } } }, "400": { "description": "INVALID_INPUT | IDEMPOTENCY_KEY_REQUIRED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "UNAUTHORIZED | AUTH_REQUIRED | KEY_REQUIRED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "INSUFFICIENT_CREDITS | QUOTE_EXCEEDS_MAX_CREDITS", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "NOT_ENTITLED | TRIAL_CAP_EXCEEDED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "NOT_FOUND", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "IDEMPOTENCY_KEY_REUSED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "CONCURRENCY_LIMIT | RATE_LIMITED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "INTERNAL", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "502": { "description": "UPSTREAM_UNAVAILABLE", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "BUDGET_EXHAUSTED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/x/resolve-url": { "get": { "operationId": "xResolveUrl", "summary": "Identify an X URL", "description": "Identify what an X (formerly Twitter) URL points at before fetching it. Give any x.com or twitter.com URL (mobile links, query params, /i/web/status forms are fine); get back {type: profile|tweet, id, handle, canonical_url}. Tweet URLs yield the numeric id for x_get_tweet; profile URLs yield the handle for x_get_profile or x_get_tweets. Costs 2 credits and parses offline without fetching the page. t.co short links cannot be expanded offline and return INVALID_INPUT telling you so; expand them in your own browser step first. Skip this tool when you already have a handle or tweet id: the other X tools accept those directly.", "x-platform": "x", "x-input-examples": [ { "summary": "Tweet URL", "value": { "url": "https://x.com/nasa/status/2054497961162478079" } }, { "summary": "Profile URL with params", "value": { "url": "https://twitter.com/nasa?ref_src=share" } } ], "parameters": [ { "name": "url", "in": "query", "required": true, "schema": { "type": "string", "description": "An X URL, e.g. https://x.com/nasa/status/2054497961162478079 or https://twitter.com/nasa." } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Required on paid-key calls; free-tier trial-key calls do not need it. Unique key per logical call (UUID recommended). Reuse the SAME key when retrying the same call; a replay returns the stored result without charging again. Reusing a key with different arguments returns IDEMPOTENCY_KEY_REUSED.", "schema": { "type": "string", "minLength": 8, "maxLength": 128 } } ], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "url_resolution envelope (schema_version 2)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/url_resolution_envelope" } } } }, "400": { "description": "INVALID_INPUT | IDEMPOTENCY_KEY_REQUIRED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "UNAUTHORIZED | AUTH_REQUIRED | KEY_REQUIRED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "INSUFFICIENT_CREDITS | QUOTE_EXCEEDS_MAX_CREDITS", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "NOT_ENTITLED | TRIAL_CAP_EXCEEDED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "NOT_FOUND", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "IDEMPOTENCY_KEY_REUSED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "CONCURRENCY_LIMIT | RATE_LIMITED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "INTERNAL", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "502": { "description": "UPSTREAM_UNAVAILABLE", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "BUDGET_EXHAUSTED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/usage": { "get": { "operationId": "getUsage", "summary": "Check credits and recent charges", "description": "Check your balance, plan, limits, and the last 10 charges (receipt ids included). Costs 0 credits and is exempt from the per-minute rate limit, so call it first to check your budget before running data tools, and any time after. Works the same on a trial key or a paid key. The response includes upgrade_url (give it to your human when credits or plan limits block you; purchases credit this account directly with no login) and manage_url (give it to your human to change or cancel a paid plan in the Stripe billing portal). Trial accounts also get a claim_url that attaches an email so the account can be recovered if the key is lost. Like every tool on this server, this one needs an API key; if this session doesn't have one yet, call mint_key first (when offered) or POST /v1/keys/mint. Not for fetching platform data.", "x-platform": null, "x-input-examples": [ { "summary": "Balance check", "value": {} } ], "parameters": [], "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "usage envelope (schema_version 2)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/usage_envelope" } } } }, "400": { "description": "INVALID_INPUT | IDEMPOTENCY_KEY_REQUIRED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "401": { "description": "UNAUTHORIZED | AUTH_REQUIRED | KEY_REQUIRED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "402": { "description": "INSUFFICIENT_CREDITS | QUOTE_EXCEEDS_MAX_CREDITS", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "403": { "description": "NOT_ENTITLED | TRIAL_CAP_EXCEEDED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "404": { "description": "NOT_FOUND", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "409": { "description": "IDEMPOTENCY_KEY_REUSED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "413": { "description": "PAYLOAD_TOO_LARGE", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "429": { "description": "CONCURRENCY_LIMIT | RATE_LIMITED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "500": { "description": "INTERNAL", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "502": { "description": "UPSTREAM_UNAVAILABLE", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } }, "503": { "description": "BUDGET_EXHAUSTED", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } } } } } }, "/v1/claim": { "post": { "operationId": "claim", "summary": "Claim a trial account", "description": "Attach an email (unverified at launch) to a trial account using the single-use token from a claim_url. The existing API key keeps working.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "token" ], "properties": { "token": { "type": "string" }, "email": { "type": "string" } } } } } }, "responses": { "200": { "description": "claimed", "content": { "application/json": { "schema": { "type": "object", "properties": { "account_id": { "type": "string" }, "status": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "email_verified": { "type": "boolean" } } } } } } } } }, "/v1/recover": { "post": { "operationId": "recover", "summary": "Request key recovery for a claimed account", "description": "Ask for a re-key link by email. Always returns the same 200 whether or not the email matches an account. Recovery email delivery is feature-flagged; while off, the response says so and points at manual recovery via hello@veezee.io.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "properties": { "email": { "type": "string" } } } } } }, "responses": { "200": { "description": "accepted", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "note": { "type": "string" } } } } } } } } }, "/v1/rekey": { "post": { "operationId": "rekey", "summary": "Issue a new API key from a recovery token", "description": "Consume a single-use recovery token (1-hour TTL, from the recovery email): a new API key is issued and every old key is revoked in one atomic batch. The token is consumed first, so if rotation ever fails the token is spent and a fresh link must be requested. The new key is shown exactly once. Balance, plan, receipts, and in-flight calls are unchanged.", "security": [], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "token" ], "properties": { "token": { "type": "string" } } } } } }, "responses": { "200": { "description": "re-keyed", "content": { "application/json": { "schema": { "type": "object", "properties": { "account_id": { "type": "string" }, "api_key": { "type": "string" }, "note": { "type": "string" } } } } } }, "401": { "description": "invalid, expired, or already-used token" } } } }, "/v1/checkout": { "post": { "operationId": "createCheckout", "summary": "Start a Checkout session", "description": "Create a Stripe Checkout session for a credit pack. Returns a hosted checkout_url to redirect the buyer to. With a key, the purchase credits that account. Without a key, payment creates a fresh account and /purchased shows its API key exactly once.", "security": [ { "bearerAuth": [] }, {} ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "pack" ], "properties": { "pack": { "type": "string", "enum": [ "flex", "production" ] } } } } } }, "responses": { "200": { "description": "session", "content": { "application/json": { "schema": { "type": "object", "properties": { "checkout_url": { "type": "string" } } } } } } } } }, "/v1/portal": { "post": { "operationId": "createPortalSession", "summary": "Open the billing portal", "description": "Create a Stripe billing-portal session for self-serve subscription management and cancellation. Humans reach the same portal without an API call: get_usage returns manage_url (a personalized link to the /manage page), or paste the API key at https://veezee.io/manage.", "security": [ { "bearerAuth": [] } ], "responses": { "200": { "description": "portal", "content": { "application/json": { "schema": { "type": "object", "properties": { "portal_url": { "type": "string" } } } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "API key: vz_live_... from a purchase at https://veezee.io/upgrade, or vz_trial_... issued by account recovery. Data routes also work with NO key under a small free per-IP daily budget." } }, "schemas": { "Problem": { "type": "object", "description": "RFC 9457 problem details with Veezee extensions.", "properties": { "code": { "type": "string", "enum": [ "INVALID_INPUT", "NOT_FOUND", "UNAUTHORIZED", "NOT_ENTITLED", "INSUFFICIENT_CREDITS", "QUOTE_EXCEEDS_MAX_CREDITS", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "CONCURRENCY_LIMIT", "RATE_LIMITED", "TRIAL_CAP_EXCEEDED", "BUDGET_EXHAUSTED", "UPSTREAM_UNAVAILABLE", "PAYLOAD_TOO_LARGE", "INTERNAL", "AUTH_REQUIRED", "KEY_REQUIRED" ] }, "message": { "type": "string" }, "param": { "type": "string" }, "doc_url": { "type": "string" }, "is_retriable": { "type": "boolean" }, "retry_after_seconds": { "type": "number" }, "valid_values": { "type": "array", "items": { "type": "string" } }, "claim_url": { "type": "string" }, "upgrade_url": { "type": "string", "description": "Present when a payment can fix this error. Give it to your human: it credits this key's account directly with no login, and the same key keeps working after payment, nothing to reconfigure." }, "credits_required": { "type": "number", "description": "Set when the balance cannot cover the call's quote: the credits the call needed." }, "offer": { "type": "object", "description": "Machine-readable purchase offer; present exactly when upgrade_url is. checkout_url is the same link as upgrade_url; resume says how to continue after payment.", "properties": { "offer_version": { "type": "number", "const": 1 }, "reason": { "type": "string", "enum": [ "INVALID_INPUT", "NOT_FOUND", "UNAUTHORIZED", "NOT_ENTITLED", "INSUFFICIENT_CREDITS", "QUOTE_EXCEEDS_MAX_CREDITS", "IDEMPOTENCY_KEY_REQUIRED", "IDEMPOTENCY_KEY_REUSED", "CONCURRENCY_LIMIT", "RATE_LIMITED", "TRIAL_CAP_EXCEEDED", "BUDGET_EXHAUSTED", "UPSTREAM_UNAVAILABLE", "PAYLOAD_TOO_LARGE", "INTERNAL", "AUTH_REQUIRED", "KEY_REQUIRED" ] }, "currency": { "type": "string", "const": "usd" }, "recommended": { "type": "string", "enum": [ "flex", "production" ], "description": "Which pack to lead with." }, "packs": { "type": "array", "items": { "type": "object", "properties": { "pack": { "type": "string", "enum": [ "flex", "production" ] }, "mode": { "type": "string", "enum": [ "payment", "subscription" ] }, "price_usd_cents": { "type": "number" }, "credits": { "type": "number" }, "credits_per_month": { "type": "number" }, "when": { "type": "string", "description": "Short label for when this pack fits." } }, "required": [ "pack", "mode", "price_usd_cents" ] } }, "rails": { "type": "array", "items": { "type": "string", "enum": [ "stripe_checkout" ] } }, "checkout_url": { "type": "string" }, "resume": { "type": "string" }, "refund_policy": { "type": "string" } }, "required": [ "offer_version", "reason", "currency", "packs", "rails", "checkout_url", "resume", "refund_policy" ] } }, "required": [ "code", "message", "doc_url", "is_retriable" ] }, "url_resolution_envelope": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "entity": { "type": "string", "const": "url_resolution" }, "platform": { "anyOf": [ { "type": "string", "enum": [ "linkedin", "reddit", "x" ] }, { "type": "null" } ] }, "canonical_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "data_as_of": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "schema_version": { "type": "string", "const": "2" }, "common": { "type": "object", "properties": { "input_url": { "type": "string" }, "type": { "type": "string", "enum": [ "person", "company", "post", "subreddit", "user", "comment", "profile", "tweet" ], "description": "What the URL points at, in the platform's own vocabulary." }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Stable platform id (URN, t3_/t1_ id, or numeric id) when resolvable." }, "handle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Human-readable slug or handle when present in the URL." }, "canonical_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "input_url", "type", "id", "handle", "canonical_url" ], "additionalProperties": false }, "platform_fields": { "type": "object", "properties": {}, "additionalProperties": false }, "freshness": { "anyOf": [ { "type": "object", "properties": { "source_retrieved_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When the data was fetched from the source. ISO 8601." }, "served_at": { "type": "string" }, "cache_age_seconds": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "served_from_cache": { "type": "boolean", "description": "True when these bytes were served from cache rather than fetched for this call. source_retrieved_at says how old they are." }, "freshness_requested": { "type": "string", "enum": [ "recent", "realtime" ] }, "freshness_served": { "type": "string", "enum": [ "recent", "realtime", "stale" ] } }, "required": [ "source_retrieved_at", "served_at", "cache_age_seconds", "served_from_cache", "freshness_requested", "freshness_served" ], "additionalProperties": false }, { "type": "null" } ] }, "usage": { "type": "object", "properties": { "receipt_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "credits_quoted": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "credits_charged": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "balance_remaining": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "free_tier_hint": { "description": "Present on free-tier trial-key calls: what budget the call drew from and that paying upgrades this same key.", "type": "string" } }, "required": [ "receipt_id", "credits_quoted", "credits_charged", "balance_remaining" ], "additionalProperties": false } }, "required": [ "entity", "platform", "canonical_url", "data_as_of", "schema_version", "common", "platform_fields", "freshness", "usage" ], "additionalProperties": false }, "person_envelope": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "entity": { "type": "string", "const": "person" }, "platform": { "anyOf": [ { "type": "string", "enum": [ "linkedin", "reddit", "x" ] }, { "type": "null" } ] }, "canonical_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "data_as_of": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "schema_version": { "type": "string", "const": "2" }, "common": { "type": "object", "properties": { "full_name": { "type": "string" }, "first_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "last_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "headline": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "location": { "anyOf": [ { "type": "object", "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Human-readable place, e.g. 'Seattle, Washington'." }, "country_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 3166-1 alpha-2 when known." } }, "required": [ "name", "country_code" ], "additionalProperties": false }, { "type": "null" } ] }, "about": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Only present when the 'about' section was requested." }, "current_position": { "anyOf": [ { "type": "object", "properties": { "company_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "company_handle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "LinkedIn company slug." }, "company_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "company_urn": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "start_year": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "company_name", "company_handle", "company_url", "company_urn", "start_year" ], "additionalProperties": false }, { "type": "null" } ] }, "experience": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "company": { "type": "object", "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "handle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "name", "handle", "url" ], "additionalProperties": false }, "positions": { "type": "array", "items": { "type": "object", "properties": { "role": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "location": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "is_current": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "start_date": { "anyOf": [ { "type": "object", "properties": { "month": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 12 }, { "type": "null" } ] }, "year": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "month", "year" ], "additionalProperties": false, "description": "Partial date as LinkedIn exposes it; month may be unknown." }, { "type": "null" } ] }, "end_date": { "anyOf": [ { "type": "object", "properties": { "month": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 12 }, { "type": "null" } ] }, "year": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "month", "year" ], "additionalProperties": false, "description": "Partial date as LinkedIn exposes it; month may be unknown." }, { "type": "null" } ] } }, "required": [ "role", "location", "is_current", "start_date", "end_date" ], "additionalProperties": false } } }, "required": [ "company", "positions" ], "additionalProperties": false } }, { "type": "null" } ], "description": "Only present when the 'experience' section was requested." }, "education": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "institution": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "institution_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "degree": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "start_year": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "end_year": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "institution", "institution_url", "degree", "start_year", "end_year" ], "additionalProperties": false } }, { "type": "null" } ], "description": "Only present when the 'education' section was requested." }, "skills": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "endorsement_count": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "name", "endorsement_count" ], "additionalProperties": false } }, { "type": "null" } ], "description": "Only present when the 'skills' section was requested." }, "followers": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "connections": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "is_verified": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "image_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "url": { "type": "string", "description": "Canonical LinkedIn profile URL." } }, "required": [ "full_name", "first_name", "last_name", "headline", "location", "about", "current_position", "experience", "education", "skills", "followers", "connections", "is_verified", "image_url", "url" ], "additionalProperties": false }, "platform_fields": { "type": "object", "properties": { "urn": { "type": "string", "description": "Stable LinkedIn URN (urn:li:fsd_profile:...). Use this for repeat lookups." }, "public_identifier": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Profile slug after /in/." }, "is_influencer": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "is_creator": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "is_hiring": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "has_premium": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "open_to_messages": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "pronoun": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "urn", "public_identifier", "is_influencer", "is_creator", "is_hiring", "has_premium", "open_to_messages", "pronoun" ], "additionalProperties": false }, "freshness": { "anyOf": [ { "type": "object", "properties": { "source_retrieved_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When the data was fetched from the source. ISO 8601." }, "served_at": { "type": "string" }, "cache_age_seconds": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "served_from_cache": { "type": "boolean", "description": "True when these bytes were served from cache rather than fetched for this call. source_retrieved_at says how old they are." }, "freshness_requested": { "type": "string", "enum": [ "recent", "realtime" ] }, "freshness_served": { "type": "string", "enum": [ "recent", "realtime", "stale" ] } }, "required": [ "source_retrieved_at", "served_at", "cache_age_seconds", "served_from_cache", "freshness_requested", "freshness_served" ], "additionalProperties": false }, { "type": "null" } ] }, "usage": { "type": "object", "properties": { "receipt_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "credits_quoted": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "credits_charged": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "balance_remaining": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "free_tier_hint": { "description": "Present on free-tier trial-key calls: what budget the call drew from and that paying upgrades this same key.", "type": "string" } }, "required": [ "receipt_id", "credits_quoted", "credits_charged", "balance_remaining" ], "additionalProperties": false } }, "required": [ "entity", "platform", "canonical_url", "data_as_of", "schema_version", "common", "platform_fields", "freshness", "usage" ], "additionalProperties": false }, "people_search_envelope": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "entity": { "type": "string", "const": "people_search" }, "platform": { "anyOf": [ { "type": "string", "enum": [ "linkedin", "reddit", "x" ] }, { "type": "null" } ] }, "canonical_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "data_as_of": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "schema_version": { "type": "string", "const": "2" }, "common": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "position": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "location": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "followers": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "is_verified": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "image_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "urn": { "type": "string" }, "public_identifier": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "is_anonymous": { "type": "boolean", "description": "True when the profile is private: it exists but linkedin_get_profile cannot dereference it. Do not retry." } }, "required": [ "name", "position", "location", "followers", "is_verified", "image_url", "url", "urn", "public_identifier", "is_anonymous" ], "additionalProperties": false } }, "cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pass back to fetch the next page. Null when exhausted." }, "next_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Ready-to-GET REST URL for the next page." }, "total_matches": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "returned_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "truncation_hint": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Present when total_matches far exceeds returned results; says which filter to add." } }, "required": [ "results", "cursor", "next_url", "total_matches", "returned_count", "truncation_hint" ], "additionalProperties": false }, "platform_fields": { "type": "object", "properties": {}, "additionalProperties": false }, "freshness": { "anyOf": [ { "type": "object", "properties": { "source_retrieved_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When the data was fetched from the source. ISO 8601." }, "served_at": { "type": "string" }, "cache_age_seconds": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "served_from_cache": { "type": "boolean", "description": "True when these bytes were served from cache rather than fetched for this call. source_retrieved_at says how old they are." }, "freshness_requested": { "type": "string", "enum": [ "recent", "realtime" ] }, "freshness_served": { "type": "string", "enum": [ "recent", "realtime", "stale" ] } }, "required": [ "source_retrieved_at", "served_at", "cache_age_seconds", "served_from_cache", "freshness_requested", "freshness_served" ], "additionalProperties": false }, { "type": "null" } ] }, "usage": { "type": "object", "properties": { "receipt_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "credits_quoted": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "credits_charged": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "balance_remaining": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "free_tier_hint": { "description": "Present on free-tier trial-key calls: what budget the call drew from and that paying upgrades this same key.", "type": "string" } }, "required": [ "receipt_id", "credits_quoted", "credits_charged", "balance_remaining" ], "additionalProperties": false } }, "required": [ "entity", "platform", "canonical_url", "data_as_of", "schema_version", "common", "platform_fields", "freshness", "usage" ], "additionalProperties": false }, "company_envelope": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "entity": { "type": "string", "const": "company" }, "platform": { "anyOf": [ { "type": "string", "enum": [ "linkedin", "reddit", "x" ] }, { "type": "null" } ] }, "canonical_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "data_as_of": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "schema_version": { "type": "string", "const": "2" }, "common": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "website_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "industry": { "type": "array", "items": { "type": "string" } }, "employee_count": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "employee_count_range": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "followers": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "founded_year": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "specialities": { "type": "array", "items": { "type": "string" } }, "headquarters": { "anyOf": [ { "type": "object", "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Human-readable place, e.g. 'Seattle, Washington'." }, "country_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 3166-1 alpha-2 when known." } }, "required": [ "name", "country_code" ], "additionalProperties": false }, { "type": "null" } ] }, "logo_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "url": { "type": "string", "description": "Canonical LinkedIn company URL." } }, "required": [ "name", "description", "website_url", "industry", "employee_count", "employee_count_range", "followers", "founded_year", "specialities", "headquarters", "logo_url", "url" ], "additionalProperties": false }, "platform_fields": { "type": "object", "properties": { "urn": { "type": "string", "description": "Stable LinkedIn URN (urn:li:fsd_company:...)." }, "linkedin_id": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Numeric company id; accepted by search filters." }, "public_identifier": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "organization_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "stock_symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "is_verified": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] } }, "required": [ "urn", "linkedin_id", "public_identifier", "organization_type", "stock_symbol", "is_verified" ], "additionalProperties": false }, "freshness": { "anyOf": [ { "type": "object", "properties": { "source_retrieved_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When the data was fetched from the source. ISO 8601." }, "served_at": { "type": "string" }, "cache_age_seconds": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "served_from_cache": { "type": "boolean", "description": "True when these bytes were served from cache rather than fetched for this call. source_retrieved_at says how old they are." }, "freshness_requested": { "type": "string", "enum": [ "recent", "realtime" ] }, "freshness_served": { "type": "string", "enum": [ "recent", "realtime", "stale" ] } }, "required": [ "source_retrieved_at", "served_at", "cache_age_seconds", "served_from_cache", "freshness_requested", "freshness_served" ], "additionalProperties": false }, { "type": "null" } ] }, "usage": { "type": "object", "properties": { "receipt_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "credits_quoted": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "credits_charged": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "balance_remaining": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "free_tier_hint": { "description": "Present on free-tier trial-key calls: what budget the call drew from and that paying upgrades this same key.", "type": "string" } }, "required": [ "receipt_id", "credits_quoted", "credits_charged", "balance_remaining" ], "additionalProperties": false } }, "required": [ "entity", "platform", "canonical_url", "data_as_of", "schema_version", "common", "platform_fields", "freshness", "usage" ], "additionalProperties": false }, "posts_envelope": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "entity": { "type": "string", "const": "posts" }, "platform": { "anyOf": [ { "type": "string", "enum": [ "linkedin", "reddit", "x" ] }, { "type": "null" } ] }, "canonical_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "data_as_of": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "schema_version": { "type": "string", "const": "2" }, "common": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "urn": { "type": "string" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "text": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601." }, "author": { "anyOf": [ { "type": "object", "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "urn": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "name", "url", "urn" ], "additionalProperties": false }, { "type": "null" } ] }, "likes": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "comments_count": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "shares": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "is_repost": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] } }, "required": [ "urn", "url", "text", "created_at", "author", "likes", "comments_count", "shares", "is_repost" ], "additionalProperties": false } }, "cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "next_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "returned_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "author_type": { "type": "string", "enum": [ "person", "company" ], "description": "What kind of entity the posts belong to." } }, "required": [ "results", "cursor", "next_url", "returned_count", "author_type" ], "additionalProperties": false }, "platform_fields": { "type": "object", "properties": {}, "additionalProperties": false }, "freshness": { "anyOf": [ { "type": "object", "properties": { "source_retrieved_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When the data was fetched from the source. ISO 8601." }, "served_at": { "type": "string" }, "cache_age_seconds": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "served_from_cache": { "type": "boolean", "description": "True when these bytes were served from cache rather than fetched for this call. source_retrieved_at says how old they are." }, "freshness_requested": { "type": "string", "enum": [ "recent", "realtime" ] }, "freshness_served": { "type": "string", "enum": [ "recent", "realtime", "stale" ] } }, "required": [ "source_retrieved_at", "served_at", "cache_age_seconds", "served_from_cache", "freshness_requested", "freshness_served" ], "additionalProperties": false }, { "type": "null" } ] }, "usage": { "type": "object", "properties": { "receipt_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "credits_quoted": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "credits_charged": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "balance_remaining": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "free_tier_hint": { "description": "Present on free-tier trial-key calls: what budget the call drew from and that paying upgrades this same key.", "type": "string" } }, "required": [ "receipt_id", "credits_quoted", "credits_charged", "balance_remaining" ], "additionalProperties": false } }, "required": [ "entity", "platform", "canonical_url", "data_as_of", "schema_version", "common", "platform_fields", "freshness", "usage" ], "additionalProperties": false }, "reddit_search_envelope": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "entity": { "type": "string", "const": "reddit_search" }, "platform": { "anyOf": [ { "type": "string", "enum": [ "linkedin", "reddit", "x" ] }, { "type": "null" } ] }, "canonical_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "data_as_of": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "schema_version": { "type": "string", "const": "2" }, "common": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "posts", "comments", "subreddits", "users" ], "description": "Which result array is populated." }, "posts": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Post id with the t3_ prefix. Pass to reddit_get_post." }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "author": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Username without the u/ prefix." }, "subreddit": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string", "description": "Subreddit name without the r/ prefix, e.g. 'selfhosted'." }, "subscribers": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "name", "subscribers" ], "additionalProperties": false }, { "type": "null" } ] }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601." }, "upvotes": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "upvote_ratio": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "comment_count": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "permalink": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Canonical reddit.com URL." }, "external_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The linked page for link posts; null for self posts." }, "preview_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Start of the post body; the full body comes from reddit_get_post." }, "flair": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "media_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "is_promoted": { "type": "boolean", "description": "True for promoted ads, which subreddit feeds include only when include_promoted=true. Organic posts are false." } }, "required": [ "id", "title", "author", "subreddit", "created_at", "upvotes", "upvote_ratio", "comment_count", "permalink", "external_url", "preview_text", "flair", "media_type", "is_promoted" ], "additionalProperties": false } }, { "type": "null" } ] }, "comments": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Comment id with the t1_ prefix." }, "author": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comment text (markdown as written)." }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "upvotes": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "permalink": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "parent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "t1_ id of the parent comment, or t3_ id when top-level." }, "depth": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "0 = top-level. Only set inside a discussion tree." }, "post": { "anyOf": [ { "type": "object", "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "subreddit": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string", "description": "Subreddit name without the r/ prefix, e.g. 'selfhosted'." }, "subscribers": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "name", "subscribers" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "title", "subreddit" ], "additionalProperties": false }, { "type": "null" } ], "description": "The post this comment belongs to. Only set outside a discussion tree (search, user history)." } }, "required": [ "id", "author", "content", "created_at", "upvotes", "permalink", "parent_id", "depth", "post" ], "additionalProperties": false } }, { "type": "null" } ] }, "subreddits": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "subscribers": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "name", "description", "subscribers" ], "additionalProperties": false } }, { "type": "null" } ] }, "users": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "username": { "type": "string" }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "karma": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "profile_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "username", "created_at", "karma", "profile_url" ], "additionalProperties": false } }, { "type": "null" } ] }, "cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pass back to fetch the next page. Null when exhausted." }, "next_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "returned_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "truncation_hint": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Present when results were cut off; says how to narrow or continue." } }, "required": [ "type", "posts", "comments", "subreddits", "users", "cursor", "next_url", "returned_count", "truncation_hint" ], "additionalProperties": false }, "platform_fields": { "type": "object", "properties": {}, "additionalProperties": false }, "freshness": { "anyOf": [ { "type": "object", "properties": { "source_retrieved_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When the data was fetched from the source. ISO 8601." }, "served_at": { "type": "string" }, "cache_age_seconds": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "served_from_cache": { "type": "boolean", "description": "True when these bytes were served from cache rather than fetched for this call. source_retrieved_at says how old they are." }, "freshness_requested": { "type": "string", "enum": [ "recent", "realtime" ] }, "freshness_served": { "type": "string", "enum": [ "recent", "realtime", "stale" ] } }, "required": [ "source_retrieved_at", "served_at", "cache_age_seconds", "served_from_cache", "freshness_requested", "freshness_served" ], "additionalProperties": false }, { "type": "null" } ] }, "usage": { "type": "object", "properties": { "receipt_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "credits_quoted": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "credits_charged": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "balance_remaining": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "free_tier_hint": { "description": "Present on free-tier trial-key calls: what budget the call drew from and that paying upgrades this same key.", "type": "string" } }, "required": [ "receipt_id", "credits_quoted", "credits_charged", "balance_remaining" ], "additionalProperties": false } }, "required": [ "entity", "platform", "canonical_url", "data_as_of", "schema_version", "common", "platform_fields", "freshness", "usage" ], "additionalProperties": false }, "subreddit_envelope": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "entity": { "type": "string", "const": "subreddit" }, "platform": { "anyOf": [ { "type": "string", "enum": [ "linkedin", "reddit", "x" ] }, { "type": "null" } ] }, "canonical_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "data_as_of": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "schema_version": { "type": "string", "const": "2" }, "common": { "type": "object", "properties": { "name": { "type": "string" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "subscribers": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "active_users": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "is_nsfw": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "topics": { "type": "array", "items": { "type": "string" } }, "url": { "type": "string", "description": "Canonical reddit.com URL for the subreddit." }, "rules": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "name", "description" ], "additionalProperties": false } }, { "type": "null" } ], "description": "Only present when include_settings was requested." }, "moderators": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ], "description": "Only present when include_settings was requested." } }, "required": [ "name", "title", "description", "subscribers", "active_users", "created_at", "is_nsfw", "topics", "url", "rules", "moderators" ], "additionalProperties": false }, "platform_fields": { "type": "object", "properties": {}, "additionalProperties": false }, "freshness": { "anyOf": [ { "type": "object", "properties": { "source_retrieved_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When the data was fetched from the source. ISO 8601." }, "served_at": { "type": "string" }, "cache_age_seconds": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "served_from_cache": { "type": "boolean", "description": "True when these bytes were served from cache rather than fetched for this call. source_retrieved_at says how old they are." }, "freshness_requested": { "type": "string", "enum": [ "recent", "realtime" ] }, "freshness_served": { "type": "string", "enum": [ "recent", "realtime", "stale" ] } }, "required": [ "source_retrieved_at", "served_at", "cache_age_seconds", "served_from_cache", "freshness_requested", "freshness_served" ], "additionalProperties": false }, { "type": "null" } ] }, "usage": { "type": "object", "properties": { "receipt_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "credits_quoted": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "credits_charged": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "balance_remaining": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "free_tier_hint": { "description": "Present on free-tier trial-key calls: what budget the call drew from and that paying upgrades this same key.", "type": "string" } }, "required": [ "receipt_id", "credits_quoted", "credits_charged", "balance_remaining" ], "additionalProperties": false } }, "required": [ "entity", "platform", "canonical_url", "data_as_of", "schema_version", "common", "platform_fields", "freshness", "usage" ], "additionalProperties": false }, "reddit_posts_envelope": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "entity": { "type": "string", "const": "reddit_posts" }, "platform": { "anyOf": [ { "type": "string", "enum": [ "linkedin", "reddit", "x" ] }, { "type": "null" } ] }, "canonical_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "data_as_of": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "schema_version": { "type": "string", "const": "2" }, "common": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Post id with the t3_ prefix. Pass to reddit_get_post." }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "author": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Username without the u/ prefix." }, "subreddit": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string", "description": "Subreddit name without the r/ prefix, e.g. 'selfhosted'." }, "subscribers": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "name", "subscribers" ], "additionalProperties": false }, { "type": "null" } ] }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601." }, "upvotes": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "upvote_ratio": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "comment_count": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "permalink": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Canonical reddit.com URL." }, "external_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The linked page for link posts; null for self posts." }, "preview_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Start of the post body; the full body comes from reddit_get_post." }, "flair": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "media_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "is_promoted": { "type": "boolean", "description": "True for promoted ads, which subreddit feeds include only when include_promoted=true. Organic posts are false." } }, "required": [ "id", "title", "author", "subreddit", "created_at", "upvotes", "upvote_ratio", "comment_count", "permalink", "external_url", "preview_text", "flair", "media_type", "is_promoted" ], "additionalProperties": false } }, "cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pass back to fetch the next page. Null when exhausted." }, "next_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Ready-to-GET REST URL for the next page." }, "returned_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "results", "cursor", "next_url", "returned_count" ], "additionalProperties": false }, "platform_fields": { "type": "object", "properties": {}, "additionalProperties": false }, "freshness": { "anyOf": [ { "type": "object", "properties": { "source_retrieved_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When the data was fetched from the source. ISO 8601." }, "served_at": { "type": "string" }, "cache_age_seconds": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "served_from_cache": { "type": "boolean", "description": "True when these bytes were served from cache rather than fetched for this call. source_retrieved_at says how old they are." }, "freshness_requested": { "type": "string", "enum": [ "recent", "realtime" ] }, "freshness_served": { "type": "string", "enum": [ "recent", "realtime", "stale" ] } }, "required": [ "source_retrieved_at", "served_at", "cache_age_seconds", "served_from_cache", "freshness_requested", "freshness_served" ], "additionalProperties": false }, { "type": "null" } ] }, "usage": { "type": "object", "properties": { "receipt_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "credits_quoted": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "credits_charged": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "balance_remaining": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "free_tier_hint": { "description": "Present on free-tier trial-key calls: what budget the call drew from and that paying upgrades this same key.", "type": "string" } }, "required": [ "receipt_id", "credits_quoted", "credits_charged", "balance_remaining" ], "additionalProperties": false } }, "required": [ "entity", "platform", "canonical_url", "data_as_of", "schema_version", "common", "platform_fields", "freshness", "usage" ], "additionalProperties": false }, "reddit_user_envelope": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "entity": { "type": "string", "const": "reddit_user" }, "platform": { "anyOf": [ { "type": "string", "enum": [ "linkedin", "reddit", "x" ] }, { "type": "null" } ] }, "canonical_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "data_as_of": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "schema_version": { "type": "string", "const": "2" }, "common": { "type": "object", "properties": { "username": { "type": "string" }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "karma": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "followers": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "is_verified": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "account_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "url": { "type": "string", "description": "Canonical reddit.com URL for the user." }, "comments": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Comment id with the t1_ prefix." }, "author": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comment text (markdown as written)." }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "upvotes": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "permalink": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "parent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "t1_ id of the parent comment, or t3_ id when top-level." }, "depth": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "0 = top-level. Only set inside a discussion tree." }, "post": { "anyOf": [ { "type": "object", "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "subreddit": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string", "description": "Subreddit name without the r/ prefix, e.g. 'selfhosted'." }, "subscribers": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "name", "subscribers" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "title", "subreddit" ], "additionalProperties": false }, { "type": "null" } ], "description": "The post this comment belongs to. Only set outside a discussion tree (search, user history)." } }, "required": [ "id", "author", "content", "created_at", "upvotes", "permalink", "parent_id", "depth", "post" ], "additionalProperties": false } }, { "type": "null" } ], "description": "Only present when the 'comments' section was requested (most recent first)." }, "posts": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Post id with the t3_ prefix. Pass to reddit_get_post." }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "author": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Username without the u/ prefix." }, "subreddit": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string", "description": "Subreddit name without the r/ prefix, e.g. 'selfhosted'." }, "subscribers": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "name", "subscribers" ], "additionalProperties": false }, { "type": "null" } ] }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601." }, "upvotes": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "upvote_ratio": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "comment_count": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "permalink": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Canonical reddit.com URL." }, "external_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The linked page for link posts; null for self posts." }, "preview_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Start of the post body; the full body comes from reddit_get_post." }, "flair": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "media_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "is_promoted": { "type": "boolean", "description": "True for promoted ads, which subreddit feeds include only when include_promoted=true. Organic posts are false." } }, "required": [ "id", "title", "author", "subreddit", "created_at", "upvotes", "upvote_ratio", "comment_count", "permalink", "external_url", "preview_text", "flair", "media_type", "is_promoted" ], "additionalProperties": false } }, { "type": "null" } ], "description": "Only present when the 'posts' section was requested." }, "subreddits": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Subreddit name without the r/ prefix, e.g. 'selfhosted'." }, "subscribers": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "name", "subscribers" ], "additionalProperties": false } }, { "type": "null" } ], "description": "Only present when the 'subreddits' section was requested: where this user is active." } }, "required": [ "username", "created_at", "karma", "followers", "is_verified", "description", "account_type", "url", "comments", "posts", "subreddits" ], "additionalProperties": false }, "platform_fields": { "type": "object", "properties": {}, "additionalProperties": false }, "freshness": { "anyOf": [ { "type": "object", "properties": { "source_retrieved_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When the data was fetched from the source. ISO 8601." }, "served_at": { "type": "string" }, "cache_age_seconds": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "served_from_cache": { "type": "boolean", "description": "True when these bytes were served from cache rather than fetched for this call. source_retrieved_at says how old they are." }, "freshness_requested": { "type": "string", "enum": [ "recent", "realtime" ] }, "freshness_served": { "type": "string", "enum": [ "recent", "realtime", "stale" ] } }, "required": [ "source_retrieved_at", "served_at", "cache_age_seconds", "served_from_cache", "freshness_requested", "freshness_served" ], "additionalProperties": false }, { "type": "null" } ] }, "usage": { "type": "object", "properties": { "receipt_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "credits_quoted": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "credits_charged": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "balance_remaining": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "free_tier_hint": { "description": "Present on free-tier trial-key calls: what budget the call drew from and that paying upgrades this same key.", "type": "string" } }, "required": [ "receipt_id", "credits_quoted", "credits_charged", "balance_remaining" ], "additionalProperties": false } }, "required": [ "entity", "platform", "canonical_url", "data_as_of", "schema_version", "common", "platform_fields", "freshness", "usage" ], "additionalProperties": false }, "reddit_thread_envelope": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "entity": { "type": "string", "const": "reddit_thread" }, "platform": { "anyOf": [ { "type": "string", "enum": [ "linkedin", "reddit", "x" ] }, { "type": "null" } ] }, "canonical_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "data_as_of": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "schema_version": { "type": "string", "const": "2" }, "common": { "type": "object", "properties": { "posts": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Post id with the t3_ prefix. Pass to reddit_get_post." }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "author": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Username without the u/ prefix." }, "subreddit": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string", "description": "Subreddit name without the r/ prefix, e.g. 'selfhosted'." }, "subscribers": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "name", "subscribers" ], "additionalProperties": false }, { "type": "null" } ] }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601." }, "upvotes": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "upvote_ratio": { "anyOf": [ { "type": "number" }, { "type": "null" } ] }, "comment_count": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "permalink": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Canonical reddit.com URL." }, "external_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The linked page for link posts; null for self posts." }, "preview_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Start of the post body; the full body comes from reddit_get_post." }, "flair": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "media_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "is_promoted": { "type": "boolean", "description": "True for promoted ads, which subreddit feeds include only when include_promoted=true. Organic posts are false." }, "content": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Full post body (markdown). Null for link posts." } }, "required": [ "id", "title", "author", "subreddit", "created_at", "upvotes", "upvote_ratio", "comment_count", "permalink", "external_url", "preview_text", "flair", "media_type", "is_promoted", "content" ], "additionalProperties": false } }, "comments": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Comment id with the t1_ prefix." }, "author": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "content": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Comment text (markdown as written)." }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "upvotes": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "permalink": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "parent_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "t1_ id of the parent comment, or t3_ id when top-level." }, "depth": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "0 = top-level. Only set inside a discussion tree." }, "post": { "anyOf": [ { "type": "object", "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "subreddit": { "anyOf": [ { "type": "object", "properties": { "name": { "type": "string", "description": "Subreddit name without the r/ prefix, e.g. 'selfhosted'." }, "subscribers": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] } }, "required": [ "name", "subscribers" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "id", "title", "subreddit" ], "additionalProperties": false }, { "type": "null" } ], "description": "The post this comment belongs to. Only set outside a discussion tree (search, user history)." } }, "required": [ "id", "author", "content", "created_at", "upvotes", "permalink", "parent_id", "depth", "post" ], "additionalProperties": false } }, { "type": "null" } ], "description": "The discussion tree, flattened in tree order with depth set. Only present with detail: 'full' or comment_id." }, "comments_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pass back as cursor to continue the discussion tree." }, "returned_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "posts", "comments", "comments_cursor", "returned_count" ], "additionalProperties": false }, "platform_fields": { "type": "object", "properties": {}, "additionalProperties": false }, "freshness": { "anyOf": [ { "type": "object", "properties": { "source_retrieved_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When the data was fetched from the source. ISO 8601." }, "served_at": { "type": "string" }, "cache_age_seconds": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "served_from_cache": { "type": "boolean", "description": "True when these bytes were served from cache rather than fetched for this call. source_retrieved_at says how old they are." }, "freshness_requested": { "type": "string", "enum": [ "recent", "realtime" ] }, "freshness_served": { "type": "string", "enum": [ "recent", "realtime", "stale" ] } }, "required": [ "source_retrieved_at", "served_at", "cache_age_seconds", "served_from_cache", "freshness_requested", "freshness_served" ], "additionalProperties": false }, { "type": "null" } ] }, "usage": { "type": "object", "properties": { "receipt_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "credits_quoted": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "credits_charged": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "balance_remaining": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "free_tier_hint": { "description": "Present on free-tier trial-key calls: what budget the call drew from and that paying upgrades this same key.", "type": "string" } }, "required": [ "receipt_id", "credits_quoted", "credits_charged", "balance_remaining" ], "additionalProperties": false } }, "required": [ "entity", "platform", "canonical_url", "data_as_of", "schema_version", "common", "platform_fields", "freshness", "usage" ], "additionalProperties": false }, "x_search_envelope": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "entity": { "type": "string", "const": "x_search" }, "platform": { "anyOf": [ { "type": "string", "enum": [ "linkedin", "reddit", "x" ] }, { "type": "null" } ] }, "canonical_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "data_as_of": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "schema_version": { "type": "string", "const": "2" }, "common": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "recent", "popular", "people" ], "description": "Which result array is populated." }, "tweets": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Numeric tweet id as a string. Pass to x_get_tweet." }, "text": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "author": { "anyOf": [ { "type": "object", "properties": { "screen_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Handle without the @, e.g. 'nasa'." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Numeric account id as a string; stable across handle changes." }, "followers": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "is_verified": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Blue-check state." } }, "required": [ "screen_name", "name", "id", "followers", "is_verified" ], "additionalProperties": false }, { "type": "null" } ] }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601." }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Canonical x.com URL." }, "views": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "likes": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "retweets": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "replies": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "quotes": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "bookmarks": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "lang": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "is_reply": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "is_retweet": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "is_quote": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "in_reply_to_screen_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "conversation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Thread root tweet id; equal to id for thread starters." }, "possibly_sensitive": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] } }, "required": [ "id", "text", "author", "created_at", "url", "views", "likes", "retweets", "replies", "quotes", "bookmarks", "lang", "is_reply", "is_retweet", "is_quote", "in_reply_to_screen_name", "conversation_id", "possibly_sensitive" ], "additionalProperties": false } }, { "type": "null" } ] }, "people": { "anyOf": [ { "type": "array", "items": { "type": "object", "properties": { "screen_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Handle without the @, e.g. 'nasa'." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Numeric account id as a string; stable across handle changes." }, "followers": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "is_verified": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Blue-check state." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "location": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "screen_name", "name", "id", "followers", "is_verified", "description", "location" ], "additionalProperties": false } }, { "type": "null" } ] }, "cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pass back to fetch the next page. Null when exhausted or for type 'people' (single page)." }, "next_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "returned_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "truncation_hint": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Present when results were cut off; says how to narrow or continue." } }, "required": [ "type", "tweets", "people", "cursor", "next_url", "returned_count", "truncation_hint" ], "additionalProperties": false }, "platform_fields": { "type": "object", "properties": {}, "additionalProperties": false }, "freshness": { "anyOf": [ { "type": "object", "properties": { "source_retrieved_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When the data was fetched from the source. ISO 8601." }, "served_at": { "type": "string" }, "cache_age_seconds": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "served_from_cache": { "type": "boolean", "description": "True when these bytes were served from cache rather than fetched for this call. source_retrieved_at says how old they are." }, "freshness_requested": { "type": "string", "enum": [ "recent", "realtime" ] }, "freshness_served": { "type": "string", "enum": [ "recent", "realtime", "stale" ] } }, "required": [ "source_retrieved_at", "served_at", "cache_age_seconds", "served_from_cache", "freshness_requested", "freshness_served" ], "additionalProperties": false }, { "type": "null" } ] }, "usage": { "type": "object", "properties": { "receipt_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "credits_quoted": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "credits_charged": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "balance_remaining": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "free_tier_hint": { "description": "Present on free-tier trial-key calls: what budget the call drew from and that paying upgrades this same key.", "type": "string" } }, "required": [ "receipt_id", "credits_quoted", "credits_charged", "balance_remaining" ], "additionalProperties": false } }, "required": [ "entity", "platform", "canonical_url", "data_as_of", "schema_version", "common", "platform_fields", "freshness", "usage" ], "additionalProperties": false }, "x_profile_envelope": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "entity": { "type": "string", "const": "x_profile" }, "platform": { "anyOf": [ { "type": "string", "enum": [ "linkedin", "reddit", "x" ] }, { "type": "null" } ] }, "canonical_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "data_as_of": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "schema_version": { "type": "string", "const": "2" }, "common": { "type": "object", "properties": { "screen_name": { "type": "string" }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "location": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "website_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The link in the profile bio, not the x.com URL." }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "followers": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "following": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "tweets_count": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "media_count": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "is_verified": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Blue-check state." }, "verified_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "e.g. 'Business' or 'Government' when applicable." }, "is_protected": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "True when tweets are visible to approved followers only." }, "image_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "banner_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "url": { "type": "string", "description": "Canonical x.com profile URL." } }, "required": [ "screen_name", "name", "description", "location", "website_url", "created_at", "followers", "following", "tweets_count", "media_count", "is_verified", "verified_type", "is_protected", "image_url", "banner_url", "url" ], "additionalProperties": false }, "platform_fields": { "type": "object", "properties": { "id": { "type": "string", "description": "Numeric account id as a string; stable across handle changes. Use for repeat lookups." }, "pinned_tweet_ids": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "is_business_account": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] } }, "required": [ "id", "pinned_tweet_ids", "is_business_account" ], "additionalProperties": false }, "freshness": { "anyOf": [ { "type": "object", "properties": { "source_retrieved_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When the data was fetched from the source. ISO 8601." }, "served_at": { "type": "string" }, "cache_age_seconds": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "served_from_cache": { "type": "boolean", "description": "True when these bytes were served from cache rather than fetched for this call. source_retrieved_at says how old they are." }, "freshness_requested": { "type": "string", "enum": [ "recent", "realtime" ] }, "freshness_served": { "type": "string", "enum": [ "recent", "realtime", "stale" ] } }, "required": [ "source_retrieved_at", "served_at", "cache_age_seconds", "served_from_cache", "freshness_requested", "freshness_served" ], "additionalProperties": false }, { "type": "null" } ] }, "usage": { "type": "object", "properties": { "receipt_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "credits_quoted": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "credits_charged": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "balance_remaining": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "free_tier_hint": { "description": "Present on free-tier trial-key calls: what budget the call drew from and that paying upgrades this same key.", "type": "string" } }, "required": [ "receipt_id", "credits_quoted", "credits_charged", "balance_remaining" ], "additionalProperties": false } }, "required": [ "entity", "platform", "canonical_url", "data_as_of", "schema_version", "common", "platform_fields", "freshness", "usage" ], "additionalProperties": false }, "x_tweets_envelope": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "entity": { "type": "string", "const": "x_tweets" }, "platform": { "anyOf": [ { "type": "string", "enum": [ "linkedin", "reddit", "x" ] }, { "type": "null" } ] }, "canonical_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "data_as_of": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "schema_version": { "type": "string", "const": "2" }, "common": { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "description": "Numeric tweet id as a string. Pass to x_get_tweet." }, "text": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "author": { "anyOf": [ { "type": "object", "properties": { "screen_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Handle without the @, e.g. 'nasa'." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Numeric account id as a string; stable across handle changes." }, "followers": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "is_verified": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Blue-check state." } }, "required": [ "screen_name", "name", "id", "followers", "is_verified" ], "additionalProperties": false }, { "type": "null" } ] }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601." }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Canonical x.com URL." }, "views": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "likes": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "retweets": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "replies": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "quotes": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "bookmarks": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "lang": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "is_reply": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "is_retweet": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "is_quote": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "in_reply_to_screen_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "conversation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Thread root tweet id; equal to id for thread starters." }, "possibly_sensitive": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] } }, "required": [ "id", "text", "author", "created_at", "url", "views", "likes", "retweets", "replies", "quotes", "bookmarks", "lang", "is_reply", "is_retweet", "is_quote", "in_reply_to_screen_name", "conversation_id", "possibly_sensitive" ], "additionalProperties": false } }, "cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pass back to fetch the next page. Null when exhausted." }, "next_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Ready-to-GET REST URL for the next page." }, "returned_count": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 } }, "required": [ "results", "cursor", "next_url", "returned_count" ], "additionalProperties": false }, "platform_fields": { "type": "object", "properties": {}, "additionalProperties": false }, "freshness": { "anyOf": [ { "type": "object", "properties": { "source_retrieved_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When the data was fetched from the source. ISO 8601." }, "served_at": { "type": "string" }, "cache_age_seconds": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "served_from_cache": { "type": "boolean", "description": "True when these bytes were served from cache rather than fetched for this call. source_retrieved_at says how old they are." }, "freshness_requested": { "type": "string", "enum": [ "recent", "realtime" ] }, "freshness_served": { "type": "string", "enum": [ "recent", "realtime", "stale" ] } }, "required": [ "source_retrieved_at", "served_at", "cache_age_seconds", "served_from_cache", "freshness_requested", "freshness_served" ], "additionalProperties": false }, { "type": "null" } ] }, "usage": { "type": "object", "properties": { "receipt_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "credits_quoted": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "credits_charged": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "balance_remaining": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "free_tier_hint": { "description": "Present on free-tier trial-key calls: what budget the call drew from and that paying upgrades this same key.", "type": "string" } }, "required": [ "receipt_id", "credits_quoted", "credits_charged", "balance_remaining" ], "additionalProperties": false } }, "required": [ "entity", "platform", "canonical_url", "data_as_of", "schema_version", "common", "platform_fields", "freshness", "usage" ], "additionalProperties": false }, "x_tweet_envelope": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "entity": { "type": "string", "const": "x_tweet" }, "platform": { "anyOf": [ { "type": "string", "enum": [ "linkedin", "reddit", "x" ] }, { "type": "null" } ] }, "canonical_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "data_as_of": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "schema_version": { "type": "string", "const": "2" }, "common": { "type": "object", "properties": { "id": { "type": "string", "description": "Numeric tweet id as a string. Pass to x_get_tweet." }, "text": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "author": { "anyOf": [ { "type": "object", "properties": { "screen_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Handle without the @, e.g. 'nasa'." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Numeric account id as a string; stable across handle changes." }, "followers": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "is_verified": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Blue-check state." } }, "required": [ "screen_name", "name", "id", "followers", "is_verified" ], "additionalProperties": false }, { "type": "null" } ] }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601." }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Canonical x.com URL." }, "views": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "likes": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "retweets": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "replies": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "quotes": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "bookmarks": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "lang": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "is_reply": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "is_retweet": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "is_quote": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "in_reply_to_screen_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "conversation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Thread root tweet id; equal to id for thread starters." }, "possibly_sensitive": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "quoted_tweet": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string", "description": "Numeric tweet id as a string. Pass to x_get_tweet." }, "text": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "author": { "anyOf": [ { "type": "object", "properties": { "screen_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Handle without the @, e.g. 'nasa'." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Numeric account id as a string; stable across handle changes." }, "followers": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "is_verified": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Blue-check state." } }, "required": [ "screen_name", "name", "id", "followers", "is_verified" ], "additionalProperties": false }, { "type": "null" } ] }, "created_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601." }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Canonical x.com URL." }, "views": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "likes": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "retweets": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "replies": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "quotes": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "bookmarks": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "lang": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "is_reply": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "is_retweet": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "is_quote": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "in_reply_to_screen_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "conversation_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Thread root tweet id; equal to id for thread starters." }, "possibly_sensitive": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] } }, "required": [ "id", "text", "author", "created_at", "url", "views", "likes", "retweets", "replies", "quotes", "bookmarks", "lang", "is_reply", "is_retweet", "is_quote", "in_reply_to_screen_name", "conversation_id", "possibly_sensitive" ], "additionalProperties": false }, { "type": "null" } ], "description": "The tweet this one quotes, when is_quote." } }, "required": [ "id", "text", "author", "created_at", "url", "views", "likes", "retweets", "replies", "quotes", "bookmarks", "lang", "is_reply", "is_retweet", "is_quote", "in_reply_to_screen_name", "conversation_id", "possibly_sensitive", "quoted_tweet" ], "additionalProperties": false }, "platform_fields": { "type": "object", "properties": {}, "additionalProperties": false }, "freshness": { "anyOf": [ { "type": "object", "properties": { "source_retrieved_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When the data was fetched from the source. ISO 8601." }, "served_at": { "type": "string" }, "cache_age_seconds": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "served_from_cache": { "type": "boolean", "description": "True when these bytes were served from cache rather than fetched for this call. source_retrieved_at says how old they are." }, "freshness_requested": { "type": "string", "enum": [ "recent", "realtime" ] }, "freshness_served": { "type": "string", "enum": [ "recent", "realtime", "stale" ] } }, "required": [ "source_retrieved_at", "served_at", "cache_age_seconds", "served_from_cache", "freshness_requested", "freshness_served" ], "additionalProperties": false }, { "type": "null" } ] }, "usage": { "type": "object", "properties": { "receipt_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "credits_quoted": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "credits_charged": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "balance_remaining": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "free_tier_hint": { "description": "Present on free-tier trial-key calls: what budget the call drew from and that paying upgrades this same key.", "type": "string" } }, "required": [ "receipt_id", "credits_quoted", "credits_charged", "balance_remaining" ], "additionalProperties": false } }, "required": [ "entity", "platform", "canonical_url", "data_as_of", "schema_version", "common", "platform_fields", "freshness", "usage" ], "additionalProperties": false }, "usage_envelope": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "entity": { "type": "string", "const": "usage" }, "platform": { "anyOf": [ { "type": "string", "enum": [ "linkedin", "reddit", "x" ] }, { "type": "null" } ] }, "canonical_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "data_as_of": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "schema_version": { "type": "string", "const": "2" }, "common": { "type": "object", "properties": { "plan": { "type": "string", "enum": [ "trial", "payg", "flex", "production" ] }, "platforms": { "type": "array", "items": { "type": "string" }, "description": "Platforms this account's key may call. Grants are explicit; write to hello@veezee.io to enable more." }, "balance_remaining": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "free_tier": { "anyOf": [ { "type": "object", "properties": { "credits_per_ip_day": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "used_today": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "remaining_today": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "resets": { "type": "string", "description": "UTC midnight when the day budget resets. ISO 8601." } }, "required": [ "credits_per_ip_day", "used_today", "remaining_today", "resets" ], "additionalProperties": false }, { "type": "null" } ], "description": "Present on trial keys: the shared per-IP day budget this key actually spends (balance_remaining stays 0 on the free tier; other callers on the same IP draw from the same pool). Null on paid plans." }, "realtime_ops_used": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "realtime_ops_limit": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ], "description": "Null means unlimited (paid plans)." }, "concurrent_limit": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "recent_receipts": { "type": "array", "items": { "type": "object", "properties": { "receipt_id": { "type": "string" }, "tool": { "type": "string" }, "credits_charged": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "created_at": { "type": "string" } }, "required": [ "receipt_id", "tool", "credits_charged", "created_at" ], "additionalProperties": false }, "description": "Up to the last 10 charges." }, "claim_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Present on trial accounts: open to attach an email so the account can be recovered if the key is lost." }, "upgrade_url": { "type": "string", "description": "Give this link to your human to add credits or upgrade; purchases credit THIS account with no login." }, "manage_url": { "type": "string", "description": "Give this link to your human to change or cancel a paid plan in the Stripe billing portal. Valid at least 24 hours; call get_usage again for a fresh one." } }, "required": [ "plan", "platforms", "balance_remaining", "free_tier", "realtime_ops_used", "realtime_ops_limit", "concurrent_limit", "recent_receipts", "claim_url", "upgrade_url", "manage_url" ], "additionalProperties": false }, "platform_fields": { "type": "object", "properties": {}, "additionalProperties": false }, "freshness": { "anyOf": [ { "type": "object", "properties": { "source_retrieved_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When the data was fetched from the source. ISO 8601." }, "served_at": { "type": "string" }, "cache_age_seconds": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "served_from_cache": { "type": "boolean", "description": "True when these bytes were served from cache rather than fetched for this call. source_retrieved_at says how old they are." }, "freshness_requested": { "type": "string", "enum": [ "recent", "realtime" ] }, "freshness_served": { "type": "string", "enum": [ "recent", "realtime", "stale" ] } }, "required": [ "source_retrieved_at", "served_at", "cache_age_seconds", "served_from_cache", "freshness_requested", "freshness_served" ], "additionalProperties": false }, { "type": "null" } ] }, "usage": { "type": "object", "properties": { "receipt_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "credits_quoted": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "credits_charged": { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, "balance_remaining": { "anyOf": [ { "type": "integer", "minimum": -9007199254740991, "maximum": 9007199254740991 }, { "type": "null" } ] }, "free_tier_hint": { "description": "Present on free-tier trial-key calls: what budget the call drew from and that paying upgrades this same key.", "type": "string" } }, "required": [ "receipt_id", "credits_quoted", "credits_charged", "balance_remaining" ], "additionalProperties": false } }, "required": [ "entity", "platform", "canonical_url", "data_as_of", "schema_version", "common", "platform_fields", "freshness", "usage" ], "additionalProperties": false } } } }