API Reference

Complete reference for the Veculo REST API. All endpoints accept and return JSON.

Authentication

All API requests must include your API key in the Authorization header as a Bearer token:

curl -H "Authorization: Bearer vk_live_abc123def456" \
  https://api.veculo.com/v1/cls_abc123/vertices/doc:arxiv-2401.001

API keys are generated in the dashboard under Settings → API Keys. Keys prefixed with vk_live_ have full access; keys prefixed with vk_test_ are read-only.

Rate limiting

API requests are rate-limited based on your cluster tier. Starter clusters allow 100 requests/second. Growth and Scale tiers have higher limits. If you exceed the limit, the API returns 429 Too Many Requests.

Base URL

All endpoints are relative to your cluster's base URL:

https://api.veculo.com/v1/{cluster_id}

Replace {cluster_id} with your cluster ID (e.g., cls_abc123).

Error responses

All errors follow a consistent format:

{
  "error": {
    "code": "not_found",
    "message": "Vertex 'doc:nonexistent' not found",
    "status": 404
  }
}

Status	Code	Meaning
400	`bad_request`	Invalid request body or parameters
401	`unauthorized`	Missing or invalid API key
403	`forbidden`	Insufficient authorizations for the requested data
404	`not_found`	Resource does not exist
409	`conflict`	Resource already exists (when using non-upsert endpoints)
429	`rate_limited`	Too many requests — back off and retry
500	`internal`	Server error — contact support if persistent

Vertices

POST/vertices

Create or update a vertex. If a vertex with the given ID already exists, its properties and visibility are updated (upsert).

Request body

Field	Type	Required	Description
`id`	string	Yes	Unique vertex identifier
`label`	string	Yes	Vertex type (e.g., "document", "person")
`properties`	object	No	Key-value pairs
`visibility`	string	No	Visibility expression (defaults to cluster default)

Requestbash

curl -X POST "https://api.veculo.com/v1/cls_abc123/vertices" \
  -H "Authorization: Bearer vk_live_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "person:turing",
    "label": "person",
    "properties": {
      "name": "Alan Turing",
      "born": 1912,
      "field": "computer-science"
    },
    "visibility": "public"
  }'

Response — 201 Createdjson

{
  "id": "person:turing",
  "label": "person",
  "properties": {
    "name": "Alan Turing",
    "born": 1912,
    "field": "computer-science"
  },
  "visibility": "public",
  "created_at": "2026-03-21T14:30:00Z"
}

POST/vertices/embedding

Create or update a vertex with a vector embedding. The embedding is indexed for similarity search. If the vertex already exists, the embedding is replaced.

Request body

Field	Type	Required	Description
`id`	string	Yes	Unique vertex identifier
`label`	string	Yes	Vertex type
`properties`	object	No	Key-value pairs
`embedding`	float[]	Yes	Vector embedding. Must match the cluster's embedding dimension.
`visibility`	string	No	Visibility expression

Requestbash

curl -X POST "https://api.veculo.com/v1/cls_abc123/vertices/embedding" \
  -H "Authorization: Bearer vk_live_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "doc:arxiv-2401.001",
    "label": "document",
    "properties": {
      "title": "Attention Is All You Need",
      "authors": "Vaswani et al.",
      "year": 2017
    },
    "embedding": [0.023, -0.114, 0.891, 0.445, -0.067, 0.234, 0.556, -0.321],
    "visibility": "public"
  }'

Response — 201 Createdjson

{
  "id": "doc:arxiv-2401.001",
  "label": "document",
  "properties": {
    "title": "Attention Is All You Need",
    "authors": "Vaswani et al.",
    "year": 2017
  },
  "embedding_dimension": 8,
  "visibility": "public",
  "created_at": "2026-03-21T14:30:00Z"
}

Embedding dimension

All embeddings in a cluster must have the same dimension. The dimension is set by the first embedding you insert. Common dimensions: 384 (MiniLM), 1536 (OpenAI), 1024 (Cohere).

GET/vertices/{id}

Retrieve a single vertex by its ID. Returns the vertex properties and metadata. The response will only include data the caller's authorizations permit.

Path parameters

Parameter	Description
`id`	The vertex ID (URL-encoded if it contains special characters)

Requestbash

curl "https://api.veculo.com/v1/cls_abc123/vertices/person:turing" \
  -H "Authorization: Bearer vk_live_abc123def456"

Response — 200 OKjson

{
  "id": "person:turing",
  "label": "person",
  "properties": {
    "name": "Alan Turing",
    "born": 1912,
    "field": "computer-science"
  },
  "visibility": "public",
  "created_at": "2026-03-21T14:30:00Z"
}

Edges

POST/edges

Create or update an edge between two vertices. If an edge with the same (source, target, edge_type) already exists, its properties and visibility are updated.

Request body

Field	Type	Required	Description
`source`	string	Yes	Source vertex ID
`target`	string	Yes	Target vertex ID
`edge_type`	string	Yes	Relationship type (e.g., "cites", "authored_by")
`properties`	object	No	Key-value pairs on the edge
`visibility`	string	No	Visibility expression

Requestbash

curl -X POST "https://api.veculo.com/v1/cls_abc123/edges" \
  -H "Authorization: Bearer vk_live_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "doc:arxiv-2312.044",
    "target": "doc:arxiv-2401.001",
    "edge_type": "cites",
    "properties": {
      "section": "related-work",
      "context": "foundational transformer architecture"
    },
    "visibility": "public"
  }'

Response — 201 Createdjson

{
  "source": "doc:arxiv-2312.044",
  "target": "doc:arxiv-2401.001",
  "edge_type": "cites",
  "properties": {
    "section": "related-work",
    "context": "foundational transformer architecture"
  },
  "visibility": "public",
  "created_at": "2026-03-21T14:31:00Z"
}

Graph traversal

POST/neighbors

Get the neighbors of a vertex, optionally filtered by edge type and limited to a given traversal depth. Returns the subgraph reachable from the specified vertex.

Request body

Field	Type	Required	Description
`vertex_id`	string	Yes	Starting vertex ID
`edge_type`	string	No	Filter to a specific edge type. Omit for all types.
`depth`	integer	No	Maximum traversal depth (default: 1, max: 5)
`limit`	integer	No	Maximum number of results (default: 100, max: 1000)
`direction`	string	No	Traversal direction: "out" (default), "in", or "both"

Requestbash

curl -X POST "https://api.veculo.com/v1/cls_abc123/neighbors" \
  -H "Authorization: Bearer vk_live_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "vertex_id": "doc:arxiv-2401.001",
    "edge_type": "cites",
    "depth": 2,
    "direction": "in"
  }'

Response — 200 OKjson

{
  "origin": "doc:arxiv-2401.001",
  "neighbors": [
    {
      "vertex": {
        "id": "doc:arxiv-2312.044",
        "label": "document",
        "properties": {
          "title": "Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks",
          "authors": "Lewis et al."
        }
      },
      "edge": {
        "edge_type": "cites",
        "properties": {
          "section": "related-work"
        }
      },
      "depth": 1
    },
    {
      "vertex": {
        "id": "doc:arxiv-2402.078",
        "label": "document",
        "properties": {
          "title": "Self-RAG: Learning to Retrieve, Generate, and Critique",
          "authors": "Asai et al."
        }
      },
      "edge": {
        "edge_type": "cites",
        "properties": {
          "section": "introduction"
        }
      },
      "depth": 2
    }
  ],
  "total": 2,
  "query_time_ms": 8
}

Vector search

POST/query/vector

Search for vertices with embeddings similar to a query vector. Optionally traverse the graph from each result to enrich the response with structural context.

Request body

Field	Type	Required	Description
`embedding`	float[]	Yes	Query vector. Must match the cluster's embedding dimension.
`top_k`	integer	No	Number of results to return (default: 10, max: 100)
`edge_type`	string	No	If set, traverse edges of this type from each result
`depth`	integer	No	Graph traversal depth from each result (default: 0, max: 3)
`min_score`	float	No	Minimum similarity score threshold (0.0 to 1.0)
`label`	string	No	Filter results to vertices with this label

Requestbash

curl -X POST "https://api.veculo.com/v1/cls_abc123/query/vector" \
  -H "Authorization: Bearer vk_live_abc123def456" \
  -H "Content-Type: application/json" \
  -d '{
    "embedding": [0.019, -0.108, 0.875, 0.439, -0.071, 0.228, 0.561, -0.318],
    "top_k": 5,
    "edge_type": "cites",
    "depth": 2,
    "min_score": 0.7,
    "label": "document"
  }'

Response — 200 OKjson

{
  "results": [
    {
      "vertex": {
        "id": "doc:arxiv-2401.001",
        "label": "document",
        "properties": {
          "title": "Attention Is All You Need",
          "authors": "Vaswani et al.",
          "year": 2017
        }
      },
      "score": 0.9847,
      "neighbors": [
        {
          "vertex": {
            "id": "doc:arxiv-2312.044",
            "label": "document",
            "properties": {
              "title": "Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks",
              "authors": "Lewis et al."
            }
          },
          "edge_type": "cites",
          "depth": 1
        },
        {
          "vertex": {
            "id": "doc:arxiv-2402.078",
            "label": "document",
            "properties": {
              "title": "Self-RAG: Learning to Retrieve, Generate, and Critique",
              "authors": "Asai et al."
            }
          },
          "edge_type": "cites",
          "depth": 2
        }
      ]
    },
    {
      "vertex": {
        "id": "doc:arxiv-2305.112",
        "label": "document",
        "properties": {
          "title": "BERT: Pre-training of Deep Bidirectional Transformers",
          "authors": "Devlin et al.",
          "year": 2019
        }
      },
      "score": 0.9234,
      "neighbors": []
    }
  ],
  "total": 2,
  "query_time_ms": 18
}

Metrics

GET/metrics

Retrieve current metrics for your cluster, including vertex and edge counts, storage usage, and query performance.

Requestbash

curl "https://api.veculo.com/v1/cls_abc123/metrics" \
  -H "Authorization: Bearer vk_live_abc123def456"

Response — 200 OKjson

{
  "cluster_id": "cls_abc123",
  "status": "running",
  "vertices": {
    "total": 145832,
    "with_embeddings": 98421
  },
  "edges": {
    "total": 523017
  },
  "storage": {
    "data_bytes": 2147483648,
    "index_bytes": 536870912
  },
  "performance": {
    "avg_query_time_ms": 12,
    "p99_query_time_ms": 45,
    "queries_last_hour": 8432
  },
  "veculo_units": 4,
  "region": "us-central1",
  "timestamp": "2026-03-21T14:35:00Z"
}

Security & ABAC Guides