Discovering Which Endpoints Your Aggregator Key Actually Exposes, From Code

Why Enumerate Endpoints Yourself?

When you use an aggregator key, the set of available endpoints may not be fully documented or could change over time. Instead of guessing, you can discover exactly what your key can reach by probing the API. This approach treats the models list as the source of truth and uses simple scripts to map out capabilities.

Start with the Models List

The /models endpoint (or its equivalent) is your primary discovery tool. It returns the models your key is authorized to use. Each model entry often includes metadata such as the provider and supported tasks. From this list, you can infer which endpoints are likely to exist.

• Fetch the models list with a GET request.
• Parse the response to extract model IDs and any capabilities (e.g., "chat", "embedding").
• Note the structure: some aggregators group models by provider or type.

Probe Common Endpoints with curl

Using the models list as a guide, test the endpoints that correspond to the capabilities you see. Common endpoints include:

• Chat completions: /v1/chat/completions
• Embeddings: /v1/embeddings
• Completions (legacy): /v1/completions
• Streaming variants: often the same endpoint with a stream: true parameter.

For each, send a minimal request with curl to check if your key is authorized and the endpoint is active. A successful response (even with an error about missing parameters) indicates the endpoint exists. A 404 or 403 suggests it's not available.

Write a Discovery Script

Manual probing is fine for a few endpoints, but a script scales better. Here's a conceptual outline:

1. Load your API key and base URL from environment variables.
2. Fetch the models list and extract unique capabilities.
3. For each capability, attempt a request to the likely endpoint with a minimal payload.
4. Record the HTTP status and any error messages.
5. Output a summary of reachable endpoints.

The script should handle errors gracefully and avoid sending unnecessary requests.

Testing Streaming Support

Streaming is often indicated by a stream parameter in the request body. To test if a model supports streaming:

• Send the same request with stream: true and stream: false.
• Compare the responses: streaming returns data in chunks (e.g., server-sent events), while non-streaming returns a single JSON object.
• Check the Content-Type header: streaming responses often use text/event-stream.

If streaming is not supported, the API may return an error or ignore the parameter. Document which models and endpoints support it.

Interpreting Results and Handling Variations

Endpoint behavior can vary by model or provider. For example, some models may only support chat, while others support both chat and embeddings. The models list should reflect this, but always verify with a test request.

• If an endpoint returns a 400 error about an invalid model, try a different model from the list that matches the capability.
• If you receive a 429 (rate limit), back off and retry later; it doesn't mean the endpoint is unreachable.
• Authentication errors (401) indicate a problem with your key, not the endpoint.

Documenting Your Findings

Keep a record of which endpoints work with which models. This is useful for development and for understanding your key's scope. Since aggregator services can update their offerings, re-run your discovery script periodically to catch changes.

Best Practices

• Always start with the models list; it's the most reliable source.
• Use minimal payloads to avoid consuming tokens unnecessarily.
• Respect rate limits and avoid aggressive polling.
• Store your API key securely and never expose it in scripts or logs.

By following these steps, you can confidently map out the endpoints your aggregator key exposes and integrate them into your applications.