Practical guides · Independent guide

DeepSeek Harness API Protocols: Choose the Right Endpoint

A working API key is only one part of a custom provider. The protocol selects the request format, the base URL selects the server, and the model ID selects a model served by that server. Check all three before retrying a failed request.

Reviewed Oct 4, 2026Developer previewIndependent guide
Evidence status: Official documentation reviewed at dsh-v0.2.1-alpha.1 (5badb15). npm and PyPI release identities are separate; no newer local runtime result is claimed. Re-check the linked first-party source after a new release candidate.
Track setup progress →

Sharing includes the public link only, without local progress or private configuration.

Start with the gateway contract

Read the endpoint documentation supplied by your provider. A provider described as OpenAI-compatible might expose Chat Completions without exposing Responses. Do not infer support from its marketing name.

  1. Record the documented protocol and base URL.
  2. Copy the exact model ID from that endpoint.
  3. Check whether the endpoint supports the tools your task needs.

Create one provider per protocol

In Settings → Models, add a Custom model API. The documented protocol values are openai-completions, openai-responses and anthropic-messages. If you need two protocols from the same gateway, create two distinct provider IDs.

  1. Use a stable lowercase provider ID; it is referenced by sessions and credentials.
  2. Save the provider and choose its model in a new session.

Read failures at the right layer

Check authentication errors against the key, unknown-model errors against the served model list, and schema errors against protocol compatibility. Change one field at a time and repeat the same small task.

  1. Keep the base URL and credentials out of public screenshots.
  2. If model discovery is unavailable, enter an explicitly documented model ID manually.

Distinguish custom protocols from the native adapter

The protocol picker configures custom pi-ai providers. The newer GitHub llm-deepseek adapter is Messages-only and has no protocol field. A protocol-is-not-configurable error belongs to that native adapter’s saved configuration; remove the unsupported field from the relevant config row instead of choosing another custom protocol.

First-party sources

Open the pinned or retrieved source before acting on a changed release candidate.

Continue by layer

DeepSeek Harness Guides: Setup, Providers and Verification
Open guide →DeepSeek Harness Setup Checklist: Save Your Progress
Open guide →DeepSeek Harness OpenAI-Compatible Endpoint Setup
Open guide →