Preface¶

The plugin approach of DeepSeek Harness (DSH) is to break different capabilities into installable tools. For API calls, letting the model read an entire OpenAPI document and construct requests on its own can lead to parameter inconsistencies, credential handling issues, and overly broad call scopes.

dsh-openapi provides a set of model-side tools for these scenarios: first list the configured APIs and operations, then inspect individual operation details, and finally execute calls under declared parameter constraints.

What This Is¶

dsh-openapi is an OpenAPI 3.x discovery and safe API calling tools plugin for DeepSeek Harness, maintained by Degurechaff5757, licensed under MIT.

It indexes configured OpenAPI 3.0 and 3.1 JSON/YAML documents and exposes three tools to the model:

• openapi_list: Discover APIs and search operations
• openapi_describe: View parameters, request body, servers, and responses for a single operation
• openapi_call: Execute calls based on declared parameters with output restrictions

Core Features¶

The following are the main capabilities provided by this plugin:

1. Supports API discovery and operation search.
2. Supports viewing parameters, request body, servers, and responses for a single operation.
3. Supports call validation and output restrictions based on declared parameters.
4. Supports static non-secret headers and credentials environment variable mapping.
5. Read-only by default, only enabling GET and HEAD.
6. Blocks URL credentials, localhost names, private IP literals, and hostnames resolving to private IPs by default.
7. Restricts response body size and blocks sensitive response headers such as set-cookie from being returned.
8. Limits the number of redirects and re-checks each redirect target.

Installation and Enablement¶

To install from GitHub, use the following command:

dsh plugin --profile web add github:Degurechaff57/dsh-openapi

After installation, the API directory is empty by default. You need to add the APIs you want to call to the profile’s cordis.patch.yml.

This plugin is plain ESM JavaScript; no build or prepare script runs when installed from GitHub.

Node engines requirement:

^22.19.0 || >=24.0.0

DeepSeek Harness is currently in developer preview; this version has been tested against source CLI 0.1.0-rc.5 and npm prerelease 0.1.0-rc.6.

Typical Usage¶

First, add an apis entry to the profile’s cordis.patch.yml. Here is a petstore example:

- id: openapi
  config:
    apis:
      - id: petstore
        source: https://petstore3.swagger.io/api/v3/openapi.json
        baseUrl: https://petstore3.swagger.io/api/v3
        allowedMethods: [GET, HEAD]

This step declares the API document source, base URL, and allowed call methods.

Then start Harness and make a request like this:

Use openapi_list to find the operation that lists pets, describe it, then call it.

openapi_list will first find the relevant operation, openapi_describe will provide parameters, request body, servers, and responses, and openapi_call will execute the call within the declared parameter scope.

If you have a local source directory, you can also install from a local path:

dsh plugin --profile web add /absolute/path/to/dsh-openapi

For interfaces requiring authentication, you can map request headers to environment variables. For example, map the Authorization header to INTERNAL_API_TOKEN with a Bearer prefix:

- id: openapi
  config:
    apis:
      - id: internal-api
        source: ./openapi/internal.yml
        baseUrl: https://api.example.com/v1
        headers:
          Accept: application/json
        credentials:
          - header: Authorization
            env: INTERNAL_API_TOKEN
            prefix: 'Bearer '
        allowedMethods: [GET, HEAD, POST]

Credential values come from environment variables, override any values provided in calls, and never appear in tool results.

Use Cases and Notes¶

This plugin is suitable for the following scenarios:

• Needing the model to call already-declared OpenAPI operations.
• Wanting to restrict callable methods, parameters, and output size.
• Needing to remove credentials from YAML and inject them via environment variables.
• Needing to avoid default access to local or private network targets.

Things to note before use:

• APIs are configured by administrators; the model cannot load arbitrary specs at runtime.
• Only GET and HEAD are allowed by default.
• allowPrivateNetwork: true can permit local or private network targets, but this is an explicit trust decision, not a substitute for network sandboxing.
• OpenAPI 3.0/3.1 and local #/... references are currently supported.
• Remote $ref documents and specialized serialization such as deepObject are not yet supported.
• The plugin runs with the current dsh process permissions; review the source code and MIT license before installation.

Conclusion¶

The value of dsh-openapi lies in confining OpenAPI calls to a set of restricted tools: the model can see operations but cannot arbitrarily expand the call scope; credentials flow through environment variables, and both responses and redirects have boundaries.

GitHub Repository: https://github.com/Degurechaff57/dsh-openapi