Skip to main content

API Overview

This section describes the VAMS REST API, which provides programmatic access to manage databases, assets, files, metadata, and search operations within the Visual Asset Management System.

Base URL​

All API endpoints are served through an Amazon API Gateway REST API. The base URL is determined by your deployment and follows this format:

https://{api-id}.execute-api.{region}.amazonaws.com

When deployed behind CloudFront or an Application Load Balancer (ALB), the base URL corresponds to your distribution or ALB domain.

Discovering the Base URL

After deployment, retrieve the API endpoint from the CDK stack outputs or from the /api/amplify-config endpoint, which returns the full API URL.

Authentication​

All API endpoints require authentication unless explicitly noted. VAMS supports three authentication methods:

MethodHeaderDescription
Cognito JWTAuthorization: Bearer {idToken}ID token from Amazon Cognito user pool authentication
External OAuth JWTAuthorization: Bearer {idToken}ID token from an external OAuth identity provider
API KeyAuthorization: {apiKey}VAMS-issued API key for programmatic access
Unauthenticated Endpoints

The following endpoints do not require authentication:

  • GET /api/amplify-config -- Returns client-side authentication configuration
  • GET /api/version -- Returns the current VAMS version :::

For detailed authentication information, see the Authentication page.

Content Type​

All request and response bodies use JSON format:

Content-Type: application/json

Common Response Format​

All API responses follow the API Gateway proxy response format:

{
    "statusCode": 200,
    "headers": {
        "Content-Type": "application/json",
        "Cache-Control": "no-cache, no-store"
    },
    "body": "{...}"
}

The body field contains a JSON-encoded string. When successful, the body contains the response data. When an error occurs, the body contains an error message.

Success Response​

{
    "message": "Success",
    "data": { ... }
}

Error Response​

{
    "message": "Description of the error"
}

Error Codes​

VAMS uses standard HTTP status codes to indicate the result of an API request.

Status CodeDescription
200The request succeeded.
400Bad request. The request contains invalid parameters, fails validation, or targets a feature that is disabled (for example, Cognito user management when Cognito is not enabled).
401Unauthorized. No VAMS handler returns this code; API Gateway returns it when a request carries no credential.
403Forbidden. The authenticated user does not have permission for the requested action.
404Not found. The requested resource does not exist, or a feature-gated resource is unavailable (for example, search when the OpenSearch feature is not enabled).
500Internal server error. An unexpected error occurred on the server.

Pagination​

Many list endpoints support pagination using a token-based pattern. The following query parameters control pagination:

ParameterTypeDescription
maxItemsintegerMaximum number of items to return in a single response.
pageSizeintegerNumber of items per page (equivalent to maxItems for most endpoints).
startingTokenstringBase64-encoded continuation token from a previous response.

Default and maximum values for maxItems and pageSize vary by listing:

ListingmaxItems defaultpageSize defaultMaximum
Assets (all, or within a database)30,0003,000maxItems 30,000; pageSize 10,000
Asset files10,000100 (1,500 with basic=true)maxItems 30,000; pageSize 10,000
Asset versions1,0001,0001,000 for each
Databases10,00010,000maxItems 30,000; pageSize 10,000
Bucket configurations3,0003,000maxItems 30,000; pageSize 10,000
Metadata (asset, file, database, asset link)1,0001001,000 for each
Metadata schemas30,0003,000maxItems 30,000; pageSize 10,000
Constraints30,0003,000maxItems 30,000; pageSize 10,000
Roles, tags, tag types, and user roles30,0003,000maxItems 30,000; pageSize 10,000; roles, tags and tag types reduce a larger value rather than rejecting it
Pipelines and workflows100100500 for each; a larger value is reduced to 500 rather than rejected
Comments10,00010,000maxItems 30,000; pageSize 10,000; a larger value is reduced, not rejected
Subscriptions10,00010,000None

Unless the table says otherwise, a listing with a maximum rejects a larger value with 400 rather than reducing it to the maximum, so a caller asking for more than one response can hold learns that from the answer instead of reading a shortened page as the complete set. A listing with no maximum accepts the value as given. Amazon Cognito user listings are capped at 60 items per page. Rely on the NextToken in each response rather than assuming a fixed page size — the whole set is reachable by following it whatever the page size.

Paginated Response​

When more results are available, the response includes a NextToken field:

{
    "Items": [ ... ],
    "NextToken": "eyJkYXRhYmFzZUlkIjoibXktZGIiLCAiYXNzZXRJZCI6Im15LWFzc2V0In0="
}

To retrieve the next page, pass the NextToken value as the startingToken query parameter in the subsequent request.

Pagination Best Practice

Always check for the presence of NextToken in the response. If it is absent, you have retrieved all available results.

Rate Limiting​

The API Gateway enforces rate limits to protect the system from excessive traffic.

SettingDefaultDescription
globalRateLimit50 requests/secondSteady-state request rate across all clients.
globalBurstLimit100 requestsMaximum burst capacity for short traffic spikes.

These values are configurable at deployment time through the app.api.apiGatewayRest.globalRateLimit and app.api.apiGatewayRest.globalBurstLimit configuration settings.

When rate limits are exceeded, the API returns an HTTP 429 Too Many Requests response.

CORS Configuration​

The API Gateway is configured with permissive CORS settings to support browser-based clients:

SettingValue
Allowed Origins* (all origins)
Allowed MethodsGET, POST, PUT, DELETE, HEAD, OPTIONS
Allowed HeadersAuthorization, Content-Type, and standard headers
CredentialsNot included (false)

Presigned URLs​

Several operations return presigned S3 URLs for direct file access. These include:

  • Asset downloads (POST /database/{databaseId}/assets/{assetId}/download) -- Returns a time-limited presigned URL for downloading a file.
  • File uploads (POST /uploads) -- Returns presigned URLs for uploading files directly to S3.
  • Asset streaming (GET /database/{databaseId}/assets/{assetId}/download/stream/{proxy+}) -- Streams file content through the API Gateway with byte-range support.
Presigned URL Expiration

Presigned URLs have a configurable timeout controlled by the PRESIGNED_URL_TIMEOUT_SECONDS environment variable. Plan to use generated URLs promptly after receiving them.

API Versioning​

The current VAMS API does not use explicit version prefixes in the URL path. All endpoints are accessed at their base paths (e.g., /database/{databaseId}/assets).

Version information can be retrieved from the GET /api/version endpoint:

{
    "version": "<current-version>"
}

API Endpoint Categories​

The VAMS API is organized into the following functional groups:

CategoryDescriptionDocumentation
AuthenticationAuthentication providers, runtime configuration, web route authorization, login profilesAuthentication
DatabasesDatabase CRUD and the bucket configurations a database is created againstDatabases
AssetsAsset CRUD, archive/unarchive, download, export, history, single-call ingestAssets
Asset VersionsAsset version creation, retrieval, revert, archive/unarchiveAsset Versions
FilesFile listing, operations, upload, streaming, preview managementFiles
MetadataMetadata CRUD for assets, files, databases, and asset links, plus metadata schemasMetadata
SearchFull-text and structured search across assets and filesSearch
PipelinesPipeline CRUD, configuration templates, and template tag schemasPipelines
WorkflowsWorkflow CRUD, triggers, and execution launch, listing, detail, logs, re-run, and abortWorkflows
Asset LinksRelationships between assets, with optional tags and tree viewsAsset Links
CommentsReview comments attached to an asset versionComments
TagsTags and tag types, global or scoped to a databaseTags
SubscriptionsEvent subscriptions and notification opt-inSubscriptions
AuthorizationPermission constraints, API route listings, roles, user-role assignments, Cognito users, API keysAuthorization
Add-onsEndpoints contributed by optional add-onsAdd-ons