Documentation

Python

pip install gateco

from gateco_sdk import GatecoClient

with GatecoClient("https://api.gateco.ai") as client:
    client.login("admin@company.com", "password")

    # Execute a permission-aware retrieval
    result = client.retrievals.execute(
        connector_id="conn_abc",
        principal_id="user_123",
        query_vector=[0.1, 0.2, 0.3, ...],
        top_k=10,
    )

    for item in result.results:
        print(item.vector_id, item.score)

TypeScript

npm install @gateco/sdk

import { GatecoClient } from "@gateco/sdk";

const client = new GatecoClient({
  baseUrl: "https://api.gateco.ai",
});
await client.login("admin@company.com", "password");

// Execute a permission-aware retrieval
const result = await client.retrievals.execute({
  connectorId: "conn_abc",
  principalId: "user_123",
  queryVector: [0.1, 0.2, 0.3],
  topK: 10,
});

for (const item of result.results) {
  console.log(item.vectorId, item.score);
}
client.close();

CLI

pip install gateco

# Login
gateco login --email admin@company.com --password secret

# Test your connector
gateco connectors test conn_abc

# Execute a retrieval
gateco retrieve --connector-id conn_abc \
  --principal-id user_123 \
  --vector-file embedding.json --top-k 10

Create a Connector

# Python
connector = client.connectors.create(
    name="Production Pinecone",
    type="pinecone",
    config={
        "api_key": "pk-...",
        "environment": "us-east-1",
        "index_name": "knowledge-base",
    },
)

# Test the connection
result = client.connectors.test(connector.id)
print(result.status, result.latency_ms)

Supported Connectors

Metadata Resolution Modes

Gateco resolves policy-relevant metadata via a configurable hierarchy per connector:

• •sidecar (default) — Metadata managed in Gateco's own registry
• •inline — Metadata extracted from vector payloads (requires metadata_field_mapping)
• •sql_view — Metadata read from a Postgres view (Postgres-family connectors only)
• •auto — Tries inline → sql_view → sidecar in order

Create a Policy

# Python — RBAC policy with proper condition format
policy = client.policies.create(
    name="Engineering Data Access",
    type="rbac",
    effect="allow",
    description="Allow engineering team to access internal docs",
    resource_selectors=["connector_abc"],
    rules=[{
        "effect": "allow",
        "priority": 1,
        "description": "Engineers can access internal docs",
        "conditions": [
            # resource. prefix = check resource metadata
            {"field": "resource.classification", "operator": "lte", "value": "internal"},
            # principal. prefix = check requesting identity
            {"field": "principal.roles", "operator": "contains", "value": "engineer"},
        ],
    }],
)

# Activate the policy
client.policies.activate(policy.id)

Policy Lifecycle

Policies go through three states:

• •Draft — Created but not enforced. Safe to edit and test.
• •Active — Enforced on all retrievals. Use the Access Simulator (Pro) to test before activating.
• •Archived — Retained for audit history but no longer enforced.

Policy Condition Fields

Condition fields MUST be prefixed with resource. or principal. — bare field names silently resolve against the principal, not the resource.

• •Resource fields: resource.classification, resource.sensitivity, resource.domain, resource.labels, resource.encryption_mode
• •Principal fields: principal.roles, principal.groups, principal.attributes.*
• •Operators: eq, ne, in, contains, lte (ordered level comparison), gte (ordered level comparison)
• •WARNING: Bare field names (e.g., "classification" without prefix) check principal attributes, not resource metadata
• •Deny policy gotcha: when a deny policy's selectors match but no rules match, the policy-level effect=deny fires. Add a catch-all allow rule to deny only specific conditions.

Single Document

response = client.ingest.document(
    connector_id="conn_abc",
    external_resource_id="doc-quarterly-report",
    text="Q4 2025 financial results...",
    classification="confidential",
    sensitivity="high",
    domain="finance",
    labels=["quarterly", "financial"],
    owner_principal_id="user_cfo",
)
print(f"Ingested {response.chunk_count} chunks")

Batch Ingestion

response = client.ingest.batch(
    connector_id="conn_abc",
    records=[
        {
            "external_resource_id": "doc-001",
            "text": "First document content...",
            "classification": "internal",
        },
        {
            "external_resource_id": "doc-002",
            "text": "Second document content...",
            "classification": "public",
        },
    ],
)
print(f"Ingested {response.total_chunks} total chunks")

CLI Ingestion

# Single file
gateco ingest report.txt --connector-id conn_abc \
  --classification confidential --sensitivity high

# Batch directory
gateco ingest-batch ./documents --connector-id conn_abc \
  --glob "*.md"

Suggest & Apply

# Scan resources and get suggestions
suggestions = client.connectors.suggest_classifications(
    connector_id="conn_abc",
    scan_limit=1000,
    sample_size=10,
)

for s in suggestions.suggestions:
    print(f"{s.resource_key}: {s.suggested_classification} "
          f"({s.confidence:.0%}) — {s.reasoning}")

# Apply approved suggestions
result = client.connectors.apply_suggestions(
    connector_id="conn_abc",
    suggestions=suggestions.suggestions,
)
print(f"Applied {result.applied}, created {result.resources_created} resources")

Classification Levels

Run a Simulation

# Python
result = client.simulator.run(
    principal_id="user_123",
    connector_id="conn_abc",
)

print(f"Matched: {result.matched_count}")
print(f"Allowed: {result.allowed_count}")
print(f"Denied: {result.denied_count}")

for trace in result.traces:
    print(f"  {trace.resource_id}: {trace.decision} — {trace.reason}")

Query Audit Events

# List recent retrieval events
page = client.audit.list(
    event_types="retrieval_allowed,retrieval_denied",
    per_page=50,
)

for event in page.items:
    print(f"{event.event_type} by {event.actor} at {event.created_at}")

# Export (Pro tier)
export = client.audit.export_csv(
    date_from="2025-01-01",
    date_to="2025-03-31",
    format="csv",
)

Event Types

Audit events are grouped into categories:

• •User — login, logout, settings_changed
• •Connector — added, updated, tested, removed, sync events
• •Policy — created, updated, activated, archived, deleted
• •Retrieval — allowed, denied (with full policy trace)
• •Data — metadata_bound, document_ingested, batch_ingested
• •Identity Provider — added, updated, removed, synced
• •Pipeline — created, updated, run, error

Authentication

# Login to get JWT tokens
curl -X POST https://api.gateco.ai/api/auth/login \
  -H "Content-Type: application/json" \
  -d '{"email":"admin@company.com","password":"secret"}'

# Use the access token
curl https://api.gateco.ai/api/connectors \
  -H "Authorization: Bearer <access_token>"

Key Endpoints

Search Modes

Pass search_mode to retrievals.execute() (and answers.execute()) to control how the underlying vector store is queried. Policy enforcement runs after the search result set is assembled, regardless of mode.

• •vector (default) — Dense embedding similarity search. Pass query_vector. Best for semantic questions.
• •keyword — Sparse BM25-style keyword search. Pass query as a plain string. Best for exact terminology lookups.
• •hybrid — Blends vector and keyword scores. Pass query and alpha (1.0 = all-vector, 0.0 = all-keyword). Best general-purpose mode.
• •grep — Literal substring / regex scan. Pass query as the pattern. Returns match_count and sort_order on the result. Best for log IDs, error codes, or exact strings.

# Keyword search — exact terminology
result = client.retrievals.execute(
    connector_id="conn_abc",
    principal_id="user_123",
    query="quarterly revenue report",
    search_mode="keyword",
    top_k=10,
)

# Hybrid search — blend vector + keyword (alpha controls the mix)
result = client.retrievals.execute(
    connector_id="conn_abc",
    principal_id="user_123",
    query="quarterly revenue report",
    search_mode="hybrid",
    alpha=0.5,  # 1.0=all-vector, 0.0=all-keyword
    top_k=10,
)

# Grep search — literal pattern / regex scan
result = client.retrievals.execute(
    connector_id="conn_abc",
    principal_id="user_123",
    query="ERR-4021",
    search_mode="grep",
)
print(result.match_count, result.sort_order)

# Answer synthesis also accepts search_mode
answer = client.answers.execute(
    query="What's our Q4 revenue?",
    connector_id="conn_abc",
    principal_id="user_123",
    search_mode="hybrid",
    alpha=0.5,
)

Rate Limits & Plan Limits

Supported Providers

Configure a Provider

# Python
idp = client.identity_providers.create(
    name="Company Okta",
    type="okta",
    config={
        "domain": "company.okta.com",
        "api_token": "...",
    },
)

# Sync principals from the provider
client.identity_providers.sync(idp.id)

Auto-Sync Configuration

Enable scheduled sync to keep principals up to date automatically. Set a sync interval (15, 30, or 60 minutes) on any connected IDP. Gateco uses PostgreSQL advisory locks for multi-instance coordination, so only one instance runs sync per IDP per interval. Disable the scheduler with DISABLE_SYNC_SCHEDULER=true.

# Update IDP with sync interval (via API)
client.identity_providers.update(
    idp.id,
    sync_config={"sync_interval_minutes": 30},
)

SCIM Provisioning (Enterprise)

Enterprise plans support inbound SCIM v2 provisioning for real-time user and group sync. Generate a SCIM bearer token, configure your IDP to push changes to the Gateco SCIM endpoint, and users/groups are provisioned automatically. SCIM tokens are one-per-IDP — generating a new token revokes the previous one.

# Generate a SCIM token (plaintext returned once)
token = client._request(
    "POST",
    f"/api/identity-providers/{idp.id}/scim-token",
)
# Configure your IDP with:
#   Endpoint: https://api.gateco.ai/api/scim/v2
#   Bearer Token: token["token"]

SCIM Endpoints