HTTP Shapes

SDK users usually call VelaClient, but understanding the HTTP shapes is useful when debugging failures or implementing a proxy.

Endpoints

Endpoint	Method	SDK method	Purpose
/api/connect-sessions	POST	createConnectSession()	Create a Hosted Connect session
/api/delegations/status	GET	getDelegationStatus()	Status snapshot before readiness / prepare
/api/authorizations/check	POST	authorizeExecution()	Check execution permission and issue relay access
/api/executions/report	POST	recordExecutionResult()	Completed / failed audit report
/api/delegations/:id/revoke	POST	revokeDelegation()	Revoke delegation
/api/audit-events	GET	listAuditEvents()	Fetch audit events

authorizeExecution Input

import type { AuthorizationRequest } from "@vel4ai/contracts";

export const authorizationRequest: AuthorizationRequest = {
  appId: "app_1",
  customerTenantId: "customer_1",
  delegationId: "delegation_1",
  estimatedCostUsd: 0.05,
  zeroDataRetentionCapable: false,
  modelSlot: {
    slotId: "chat",
    selectionMode: "locked",
    requiredModel: "openai/gpt-4o-mini",
  },
};

recordExecutionResult Input

import type { RecordExecutionResultInput } from "@vel4ai/contracts";

export const resultInput: RecordExecutionResultInput = {
  appId: "app_1",
  customerTenantId: "customer_1",
  delegationId: "delegation_1",
  executionSessionId: "session_1",
  requestedModel: "openai/gpt-4o-mini",
  resolvedExecutionTarget: "openai/gpt-4o-mini",
  status: "completed",
  usageSummary: {
    inputTokens: 12,
    outputTokens: 24,
    totalTokens: 36,
    estimatedCostUsd: 0.05,
  },
};

Credentials

createFetchTransport() attaches x-vela-app-id, x-vela-app-token, and the compatibility header x-vela-app-key. Prefer appToken and VELA_APP_TOKEN in new code.