Ask in:ChatGPTClaudeCopy prompt

VECK API DocumentationAPI v1

REST API for seamless integration into venture capital monitoring and internal workflows: cards (projects / signals), participants (funds, investors, people), interactions, and reference data for filters. All routes are versioned under /v1/.

Overview

Quick start

Minimal request

• Base URL: https://api.theveck.com
• Header: Authorization: Token <your_token> on every request
• Example: GET https://api.theveck.com/v1/cards/?limit=10

Authentication

Every endpoint requires a valid API token. Send it in the Authorization header using the Token scheme (see Quick start). Invalid or missing credentials result in 401 (see Error Handling).

Conventions

Where to read next: endpoint details under Cards and Participants; valid slugs under Reference Data; response field reference under Glossary; errors and payload shape under Notes.

Cards

List and inspect cards (projects / signals): pagination, filters, semantic search, detail and interactions. Use Reference Data below for slug values used in query parameters.

Get Cards List (GET)

GET /v1/cards/

Get a list of signal cards (projects) with pagination, sorting, and filtering support.

Main Parameters

Sort presets

Custom sort: field:direction or field1:dir1,field2:dir2
Available fields: created_at, updated_at, name, interactions_count, latest_signal_date
Directions: asc, desc

Filters

Semantic search (cards)

What it is: Semantic search finds cards by meaning and context, not just by exact words. For example, a query like "crypto exchange" can match projects about DeFi or trading platforms even if those exact words are not in the card text. Results are ordered by how closely they match the intent of your query.

• semantic (boolean-like string) — enables this search mode when used together with search:

  • Allowed values: 1, true, yes (case-insensitive)
  • Behavior:
    • Text from search is transformed into semantic vectors by our internal retrieval pipeline.
    • All other filters (stages, rounds, categories, locations, participants, etc.) are applied first.
    • Matching cards with non-null embeddings are ordered by cosine similarity to the query embedding.
    • Results are filtered by relevance threshold (default min_similarity=0.3).
    • Each result includes a similarity field (0.0-1.0) indicating how well it matches the query.
    • Pagination (limit, offset) works as usual.
  • If embeddings are temporarily unavailable, the API may return 503 with error: "semantic_unavailable".

• min_similarity (float) — minimum cosine similarity threshold for semantic search (only used with semantic=1):

  • Range: 0.0 to 1.0 (where 1.0 = perfect match, 0.0 = no similarity)
  • Practical range: 0.3 to 0.9 (values above 0.9 are extremely rare and indicate near-perfect matches)
  • Default: 0.3 (filters out clearly irrelevant results while keeping good matches)
  • Recommended values:
    • 0.7-0.9 — very strict (only highly relevant results, fewer matches)
    • 0.5-0.7 — strict (good quality results)
    • 0.3-0.5 — default (balanced, filters obviously irrelevant)
    • 0.0-0.3 — lenient (more results, may include less relevant)
  • Higher values = more relevant results, but fewer matches
  • Lower values = more results, but may include less relevant ones
  • Note: Setting min_similarity above 0.9 will likely return very few or no results, as perfect matches are extremely rare

Semantic metadata in response: when semantic=1, response includes meta.semantic with enabled, min_similarity, and ranking so clients can render/debug ranking mode.

Date Filters

Filtering Logic

• Different filter groups are combined with AND (except stages and rounds)
• Values within each group are combined with OR
• Stages and rounds are combined with OR — if both stages and rounds are specified, cards matching either the stage OR the round will be returned
• When a parent category is specified, all child categories are automatically included
• When a region is specified, cards from all locations in that region are returned

Examples:

• stages=seed&rounds=raising_now — returns cards with stage seed OR round raising_now
• stages=seed,series_a&categories=ai — returns cards with stage seed OR series_a, AND category ai

Example Request

GET /v1/cards/?limit=20&offset=0&sort=trending&categories=ai,saas&stages=seed&include_user_data=true
Authorization: Token <your_token>

Example Response

meta.sort echoes the effective sort preset or custom sort string from the request. meta.fields is the sorted selected field allowlist (view, default set, or fields=). Some keys (e.g. similarity) are only present on each card when semantic search is enabled; they may still appear in meta.fields as part of the default template.

Response fields (cards list)

• Always present in default view (required): id, slug, name, public_url, interactions_count, trending, stage, round, categories, created_at, updated_at, social_links, open_to_intro, has_intro_request. The stage and round objects always have name; slug may be null.
• User-scoped optional field: user_data is included in personalized mode (include_user_data=true); note and folders inside it may be null/empty.
• May be null (optional): description, image, url, location, last_round, last_interaction_at, first_interaction_at. If location is present, its subfields (formatted, slug, city, state, country, region, region_slug, type) may be null.
• Semantic search only: similarity (float, 0.0-1.0) — cosine similarity score indicating how well the card matches the semantic query. Only present when semantic=1 is used. Higher values (closer to 1.0) indicate better matches. Practical range: typically 0.3-0.9; values above 0.9 are extremely rare.
• Field selection: when fields or view=compact is used, response includes the selected subset of top-level fields.

Get Cards List (POST)

POST /v1/cards/

Same listing and filtering behavior as Get Cards List (GET), but parameters are sent in a JSON body. Use this when filters are too large for a query string (e.g. many categories or participant slugs).

Important: POST accepts the same parameters as GET, but in the JSON body. Lists are arrays, not comma-separated strings.

Request body (JSON)

All parameters mirror GET; passing details:

• limit (integer) — number of records per page (maximum 100, default 20)
• offset (integer) — offset from the start of the list (default 0)
• include_total (boolean) — include total count in pagination (true by default)
• sort (string) — sorting: trending, recent, most_active or custom format field:direction
• include_user_data (boolean) — includes user data (favorites, notes, folders)
• view (string) — default or compact
• fields (array[string] or comma-separated string) — top-level fields to return
• stages (array[string]) — filter by stages (array): ["seed", "series_a"]
• rounds (array[string]) — filter by rounds (array): ["raising_now", "just_raised"]
• categories (array[string]) — filter by categories (array): ["ai", "saas"]
• locations (array[string]) — filter by locations (array): ["san_francisco_ca", "bay_area"]
• participants (array[string]) — filter by participants (array): ["investor-fund"]
• display_preference (string) — filter by type: web3, web2, all
• filter_id (integer) — apply saved user filter
• folder_ids (array[integer]) — filter by folders (array): [1, 2, 3]
• created_after, created_before (string) — filter by creation date (format: YYYY-MM-DD)
• updated_after, updated_before (string) — filter by update date
• last_interaction_after, last_interaction_before (string) — filter by last interaction date
• first_interaction_after, first_interaction_before (string) — filter by first interaction date
• search (string) — optional text query; with "semantic": true it is used for semantic search over embeddings
• semantic (boolean) — enables semantic search when used with search; same behavior as in GET cards list

Example Request

Basic POST request:

POST /v1/cards/
Content-Type: application/json
Authorization: Token <your_token>

{
  "limit": 20,
  "offset": 0,
  "sort": "recent"
}

POST with large filter volume:

POST /v1/cards/
Content-Type: application/json
Authorization: Token <your_token>

{
  "limit": 50,
  "offset": 0,
  "sort": "trending",
  "stages": ["seed", "series_a", "series_b"],
  "categories": ["ai", "saas", "b2b", "fintech", "healthcare"],
  "locations": ["san_francisco_ca", "new_york_ny", "london_united_kingdom"],
  "participants": ["investor-fund-1", "investor-fund-2", "investor-fund-3"],
  "created_after": "2024-01-01",
  "folder_ids": [1, 2, 3, 4, 5]
}

POST with custom sorting:

POST /v1/cards/
Content-Type: application/json
Authorization: Token <your_token>

{
  "limit": 20,
  "offset": 0,
  "sort": "name:asc,created_at:desc",
  "categories": ["ai", "saas"]
}

Note: Custom sorting is passed as a string in format field:direction,field:direction (same format as in GET request). For example:

• "sort": "name:asc" — sort by name ascending
• "sort": "created_at:desc,interactions_count:desc" — first by creation date (descending), then by interactions count (descending)

Example Response

Response format is identical to GET method (see above).

Get Card by Slug

GET /v1/cards/<slug>/

Get detailed information about a specific card by its slug.

Parameters

Response metadata

Example Request

GET /v1/cards/project-slug/?include_user_data=true
Authorization: Token <your_token>

Example Response

Get Card Interactions

GET /v1/cards/<slug>/interactions/

Get all interactions (signals) for a card with pagination.

Parameters

Example Request

GET /v1/cards/project-slug/interactions/?limit=50&offset=0
Authorization: Token <your_token>

Example Response

Reference Data

All reference values (stages, rounds, categories, locations, participant types, folders, filters) should be loaded from the meta endpoints below. They return complete slug/ID lists for filters and UI.

Note: Responses may include lightweight counters in meta (e.g. total, us_regions_total, world_regions_total) for caching and UI.

Categories

GET /v1/cards/categories/

Hierarchical categories (parents and children) for categories= filters.

Example response

Stages

GET /v1/cards/stages/

Stage slugs for stages= filters (e.g. seed, series_a).

Example response

Rounds

GET /v1/cards/rounds/

Round slugs for rounds= filters (e.g. raising_now, just_raised).

Example response

Locations

GET /v1/cards/locations/

Regions and cities for locations= filters.

Example response

User Folders

GET /v1/cards/folders/

Folders for the authenticated user; use with folder_ids=.

Example response

Saved Filters

GET /v1/cards/filters/

Saved filters; apply with filter_id.

Example response

Participants

Participants are funds, investors, angels, and related entities. List, fetch by slug, batch-fetch, and resolve type slugs for type= filters.

Get Participants List

GET /v1/participants/

Get list of participants (funds, investors, angels) with pagination and filtering.

Main Parameters

Sort presets

Custom sort: field:direction or field1:dir1,field2:dir2
Available fields: name, monthly_signals
Directions: asc, desc

Filters

Semantic search (participants)

What it is: Semantic search finds participants by meaning and context, not just by exact words. For example, "web3 venture fund" can match funds that describe themselves in different terms but have the same focus. Results are ordered by how closely they match the intent of your query.

• semantic (boolean-like string) — enables this search mode when used together with search:

  • Allowed values: 1, true, yes (case-insensitive)
  • Behavior:
    • Text from search is transformed into semantic vectors by our internal retrieval pipeline.
    • All other filters (type, web3, web2, etc.) are applied first.
    • Matching participants with non-null embeddings are ordered by cosine similarity to the query embedding.
    • Results are filtered by relevance threshold (default min_similarity=0.3).
    • Each result includes a similarity field (0.0-1.0) indicating how well it matches the query.
    • Pagination (limit, offset) works as usual.
  • If embeddings are temporarily unavailable, the API may return 503 with error: "semantic_unavailable".

• min_similarity (float) — minimum cosine similarity threshold for semantic search (only used with semantic=1):

  • Range: 0.0 to 1.0 (where 1.0 = perfect match, 0.0 = no similarity)
  • Practical range: 0.3 to 0.9 (values above 0.9 are extremely rare and indicate near-perfect matches)
  • Default: 0.3 (filters out clearly irrelevant results while keeping good matches)
  • Recommended values:
    • 0.7-0.9 — very strict (only highly relevant results, fewer matches)
    • 0.5-0.7 — strict (good quality results)
    • 0.3-0.5 — default (balanced, filters obviously irrelevant)
    • 0.0-0.3 — lenient (more results, may include less relevant)
  • Higher values = more relevant results, but fewer matches
  • Lower values = more results, but may include less relevant ones
  • Note: Setting min_similarity above 0.9 will likely return very few or no results, as perfect matches are extremely rare

Example Request

GET /v1/participants/?limit=50&offset=0&type=fund&web3=true&sort=most_active
Authorization: Token <your_token>

Example Response

Note: Field is_saved appears only when include_user_data=true is specified in the request.

Get Participant by Slug

GET /v1/participants/<slug>/

Get detailed information about a participant by slug.

Parameters

Example Request

GET /v1/participants/investor-fund/?include_user_data=true
Authorization: Token <your_token>

Example Response

Get Multiple Participants

GET /v1/participants/batch/

Get multiple participants by list of slugs (batch operation, maximum 100).

Parameters

Example Request

GET /v1/participants/batch/?slugs=investor-fund,john-doe,another-fund
Authorization: Token <your_token>

Example Response

Participant Types

GET /v1/participants/types/

Type slugs for type= filters (fund, investor, angel, …).

Example response

Utilities

Health-style helpers that do not return domain objects.

Validate Token

GET /v1/token/validate/

Check that the Authorization: Token … header is accepted.

Example Request

GET /v1/token/validate/
Authorization: Token <your_token>

Example Response

200 OK with:

Glossary

Field-by-field reference for JSON payloads. Presence: required — always present for that resource/view; optional — may be omitted (e.g. sparse fieldsets); nullable — key may be present with null; semantic only — only when semantic=1 is used with search.

Card Attributes

Basic Fields

Status and Metrics

stage / round object

Categories

Each category item

Location

When location is an object

Dates

Social Links

Each social_links item

User Data (include_user_data=true)

user_data object

user_data.note

Each folder item

List and Detail (common)

Semantic Search

Card Detail Only

linkedin_data

Participant Attributes

Basic Fields

Type and Focus

Metrics

Semantic Search

Relationships

associated_with

User Data (include_user_data=true)

Participant Detail Only (sources)

Each sources item

Interaction Attributes

participant / associated_participant summary object

Pagination Attributes

Notes

Cross-cutting behavior for every endpoint: error JSON, successful payload shape, and date formats.

Error Handling

All errors are returned in JSON format:

Main Error Codes

• 401 Unauthorized — authentication required or invalid token
• 404 Not Found — resource not found
• 400 Bad Request — data validation error
• 429 Too Many Requests — request limit exceeded
• 500 Internal Server Error — internal server error

Example Error Responses

Rate limit exceeded (429) - Paid access:

Rate limit exceeded (429) - Free access:

Response Format

All successful responses contain a data field with data and an optional pagination field for lists. List endpoints may also include meta:

Date Formats

Request parameters (date filters): Use YYYY-MM-DD format (e.g., 2025-01-15)

• Applies to: created_after, created_before, updated_after, updated_before, last_interaction_after, last_interaction_before, first_interaction_after, first_interaction_before

Response fields (date-time): Use ISO 8601 UTC format with time (e.g., 2025-01-15T10:30:00Z)

• Applies to: created_at, updated_at, last_interaction_at, first_interaction_at, and all datetime fields in responses

Exception: last_round field in responses uses YYYY-MM-DD format (date only, e.g., 2025-01-15)