API Reference

Complete API reference for the VECU Custody Python SDK.

API Version

This documentation covers SDK version v0.1.1, which uses Custody API v1.

SDK-Only Access

To ensure your integration remains stable and supported, always use the official SDKs. The underlying API endpoints are internal implementation details that may change in purpose, functionality, or be removed at any time without notice. Direct API access is not supported. Learn more →

The SDK methods documented here are your supported interface. Versioning is managed through SDK upgrades.

Resources

The SDK provides access to 6 resource groups:

Resource	Methods	Description
Custody Permits	4	Create, retrieve, list, and cancel custody authorizations
Transfers	4	Create transfers, check status, view history, verify integrity
Releasability	2	Query and update vehicle releasability status
Release	1	Record vehicle releases from custody
Health	2	Service health check

API Terminology

In documentation, we use "Custody Permits" to describe permissions for vehicle custody. The underlying API resource is named authorizations (e.g., client.authorizations.create()). This terminology distinction helps avoid confusion with API authentication.

Client Access

Access resources through the client instance:

from vecu_custody import CustodyClient

client = CustodyClient.sandbox(token="your-jwt-token")

# Custody Permits (authorizations resource)
client.authorizations.create(...)
client.authorizations.get(...)
client.authorizations.list(...)
client.authorizations.cancel(...)

# Transfers
client.transfers.create(...)
client.transfers.get_status(...)
client.transfers.get_history(...)
client.transfers.verify_integrity(...)

# Releasability
client.releasability.check_vin(...)
client.releasability.check_with_context(...)
client.releasability.get_cached(...)

# Releases
client.release.release(...)

# Health
client.health_check()   # Returns bool
client.get_health()     # Returns HealthResponse

Common Patterns

Pagination

List methods support auto-pagination by default:

# Auto-paginated - fetches all results
for auth in client.authorizations.list(vin="9HGBH41JXMN999999"):
    print(auth.authorization_id)

# Manual pagination with cursor
page = client.authorizations.list(
    vin="9HGBH41JXMN999999",
    limit=50,
    auto_paginate=False
)
for auth in page.authorizations:
    print(auth.authorization_id)

# Get next page using cursor
if page.next_token:
    next_page = client.authorizations.list(
        vin="9HGBH41JXMN999999",
        next_token=page.next_token,
        auto_paginate=False
    )

Filtering

List methods support filtering parameters:

# Filter by VIN
auths = client.authorizations.list(vin="9HGBH41JXMN999999")

# Filter by status
active_auths = client.authorizations.list(
    vin="9HGBH41JXMN999999",
    status="PENDING"
)

# Combine filters with pagination control
auths = client.authorizations.list(
    vin="9HGBH41JXMN999999",
    status="RELEASABLE",
    limit=100,
    auto_paginate=False
)

Error Handling

All methods may raise exceptions from the SDK's exception hierarchy:

from vecu_custody import CustodyClient
from vecu_custody.exceptions import (
    AuthorizationNotFoundError,
    ValidationError,
    CustodyError
)

client = CustodyClient.sandbox(token="your-jwt-token")

try:
    auth = client.authorizations.get(authorization_id="AUTH-12345678")
except AuthorizationNotFoundError:
    print("Authorization does not exist")
except ValidationError as e:
    print(f"Invalid request: {e}")
except CustodyError as e:
    print(f"API error: {e}")

See Error Handling for detailed exception documentation.

Async Operations

All synchronous methods have async equivalents:

from vecu_custody.aio import AsyncCustodyClient

async def main():
    async with AsyncCustodyClient.sandbox(token="your-jwt-token") as client:
        # Same API, async methods
        auth = await client.authorizations.create(
            vin="9HGBH41JXMN999999",
            origin="LOC-AUCTION-MANHEIM-ATLANTA",
            destination="LOC-DEALERSHIP-CARMAX-ORLANDO",
            person_identity_key="vecu_test123",
            authorized_by="system-integration",
            make_model="Honda Accord 2023"
        )
        result = await client.releasability.check_vin(vin="9HGBH41JXMN999999")

import asyncio
asyncio.run(main())

See Advanced Async Patterns for detailed async documentation including FastAPI integration and concurrency patterns.

Data Types

VIN Format

Vehicle Identification Numbers (VINs) must be valid 17-character strings (excludes I, O, Q):

# Valid VIN
vin = "9HGBH41JXMN999999"

# Invalid VINs
vin = "INVALID"              # Too short
vin = "9HGBH41JXMN9999999"   # Too long

Location ID Format

Location IDs follow the pattern LOC-{TYPE}-{ID}:

# Valid location IDs
origin = "LOC-AUCTION-MANHEIM-ATLANTA"
destination = "LOC-DEALERSHIP-CARMAX-ORLANDO"

Timestamp Format

All timestamps are Python datetime objects:

from datetime import datetime, timedelta

# Set validity period
auth = client.authorizations.create(
    vin="9HGBH41JXMN999999",
    origin="LOC-AUCTION-MANHEIM-ATLANTA",
    destination="LOC-DEALERSHIP-CARMAX-ORLANDO",
    person_identity_key="vecu_test123",
    authorized_by="system-integration",
    make_model="Honda Accord 2023",
    valid_until=datetime.utcnow() + timedelta(hours=24)
)

# Access timestamps
print(auth.created_at)  # datetime object

Authentication

The SDK handles authentication using JWT tokens:

# Using environment-specific class methods (recommended)
client = CustodyClient.sandbox(token="your-jwt-token")
client = CustodyClient.production(token="your-jwt-token")

# Using constructor with custom base URL
client = CustodyClient(
    token="your-jwt-token",
    base_url="https://custom-url.com/v1",
    timeout=60,
    max_retries=5
)

JWT tokens are automatically included in all requests as HTTP headers.

Credential Security

Security Best Practices

Never hardcode credentials in source code - Use environment variables or a secrets manager - Rotate JWT tokens regularly - Use different credentials for sandbox and production

Rate Limiting

The API enforces rate limits to ensure service quality. When rate limited, the SDK automatically retries with exponential backoff:

from vecu_custody.exceptions import RateLimitError

try:
    auths = client.authorizations.list(vin="9HGBH41JXMN999999")
except RateLimitError as e:
    print(f"Rate limited. Retry after {e.retry_after} seconds")

Health Check

Check API service health:

# Simple boolean check
is_healthy = client.health_check()
print(f"Service healthy: {is_healthy}")

# Detailed health information
health = client.get_health()
print(f"Status: {health.status}")      # "healthy"
print(f"Service: {health.service}")    # "vecu-custody"
print(f"Version: {health.version}")    # "0.1.0"

Resource Documentation

Detailed documentation for each resource:

Custody Permits - Vehicle custody authorization
Transfers - Custody transfer operations
Releasability - Query and update vehicle releasability status
Release - Record vehicle releases

Next Steps

Custody Permits - Start with custody permits
Error Handling - Learn about exceptions
Testing - Test your integration

Vehicle Custody