Custom Endpoints

What custom endpoints provide

Custom endpoints allow operators to register provider endpoints that implement either the Anthropic Messages API or OpenAI Chat Completions wire format. Custom providers are treated identically to built-in providers for all routing, fallback, and evidence capture requirements (provider_routing_and_model_abstraction_spec.md §4.4).

Registration requirements

A custom provider registration requires:

• base URL
• wire format declaration (anthropic or openai)
• API key secret reference (resolved via the secret management spec)
• declared model list (the set of model identifiers available at this endpoint)
• declared capability deviations (any capabilities not supported relative to the canonical wire format)
• provider class assignment (for policy routing)

Registering a custom endpoint

syndicate provider register ./providers/my-custom.yaml

The config file structure:

identity: my-custom-provider
class: approved_hosted
endpoint: https://api.example.com/v1
wire_format: openai
models:
  - model-a
  - model-b
capability_deviations:
  - approximate token counts
  - unsupported seed control

Custom providers may also be added directly:

syndicate provider add my-custom-provider \
  --url https://api.example.com/v1 \
  --wire-format openai

Wire format determination

The wire format declaration determines which adapter is used (provider_routing_and_model_abstraction_spec.md §4.4):

Capability deviations

Where a custom endpoint does not fully conform to the canonical wire format, the adapter must declare explicit deviations. Common deviations include:

• approximate token counts
• partial streaming reliability
• weak JSON adherence
• unsupported seed control
• non-standard tool-call serialization

Undeclared capability deviations are a registration defect. If discovered at invocation time, the deviation is recorded and the provider's capability record is updated.

Provider class assignment

Policy must support routing rules at provider class granularity (provider_routing_and_model_abstraction_spec.md §6):

Company policy in team or enterprise deployments may further restrict allowed providers, model families, regions, data classes per provider, and workflow-to-provider mappings.

Catalog precedence

Operator-configured custom providers take precedence over catalog-discovered providers with the same id. If both exist for a given ID, the manual configuration is used and the catalog entry is ignored (provider_routing_and_model_abstraction_spec.md §4.6.5).

Subscription-based access

Some providers authenticate via an operator's subscription account rather than an API key. Supported providers and auth flows (provider_routing_and_model_abstraction_spec.md §4.5):

OAuth PKCE flow uses S256 — the plain code challenge method is prohibited. Access tokens are refreshed automatically before expiry; if the refresh token is expired or revoked, the operator is prompted to re-authenticate.

Subscription-based providers and API key providers may coexist. Policy determines which credential is used for which workflow class.

Evidence requirements

Every invocation to a custom endpoint captures identical evidence to built-in providers (provider_routing_and_model_abstraction_spec.md §10):

• model ID and provider identifier
• verbatim request and response envelopes
• sampling parameters (temperature, top_p, max_tokens, seed, stop sequences)
• token accounting (prompt tokens, completion tokens, truncation record)
• tool call fidelity records
• non-determinism markers
• failure and degradation evidence

Each captured field is tagged as self_reported, client_captured, provider_corroborated, or middleware_derived. Provider-corroborated fields carry higher evidentiary weight.

Provider testing

Verify connectivity and capability verification:

syndicate provider test my-custom-provider
syndicate provider capabilities my-custom-provider

The test command sends a minimal well-formed request and validates the response against the declared capability descriptor, reporting any deviations.

Security

• Custom endpoints are not exempt from governed execution. Every invocation requires a valid permit.
• API key secrets are resolved via the secret management specification, never stored in plaintext config.
• TLS certificate errors must fail the fetch with no bypass option for remote endpoints.
• Network access by provider adapters must be subject to egress policy enforcement.