OpenAPI document

Everything in this reference is generated from one file. That file is published, so you do not have to read the HTML — point your own tooling at it.

What	URL
Latest, YAML	https://docs.valueverde.de/spec/partner-api.yaml
Latest, JSON	https://docs.valueverde.de/spec/partner-api.json
A pinned version	https://docs.valueverde.de/spec/<version>/partner-api.yaml (and .json)
Which versions exist	https://docs.valueverde.de/spec/index.json
Postman collection	.../spec/valueverde-partner-api.postman_collection.json

It is OpenAPI 3.1, and it is the same document the reference pages on this site are built from — there is no second, more accurate copy that we keep to ourselves.

Generate a client

curl -sS -o partner-api.yaml https://docs.valueverde.de/spec/partner-api.yaml

npx @openapitools/openapi-generator-cli generate \
  -i partner-api.yaml \
  -g typescript-fetch \
  -o ./valueverde-client

Swap -g for any generator you prefer — java, python, go, csharp. We do not yet ship a maintained SDK in any language, so the generated client is the client; treat it as yours and check it into your repository.

Import it into Postman

https://docs.valueverde.de/spec/valueverde-partner-api.postman_collection.json

Paste that into Postman's Import → Link. The collection is generated from the same document on every docs build, so it cannot drift from the contract.

Set clientId and clientSecret in the collection variables, send 0. Get an access token, and work down the folders — the token, the cooperative id, the investor id and the purchase id are all captured into variables as you go, so a top-to-bottom run needs no copy-paste. It points at staging by default.

Run it as a mock

The spec carries examples, so a local mock server needs nothing from us:

npx @stoplight/prism-cli mock partner-api.yaml

That gets you shapes and status codes without credentials. It will not model state — a purchase you place against the mock does not appear in a later holdings call — so use it to build against the contract, then move to staging for behaviour.

Contract-test against it

Because the spec is fetchable, "does the API still match its documentation" is a test you can run in your own CI rather than a question you have to ask us:

npx @redocly/cli lint https://docs.valueverde.de/spec/partner-api.yaml

Pin the version you generated against

info.version in the document tracks the document, not the URL prefix — the API itself is /v1 and stays /v1 until a breaking change, per Versioning. A generated client, though, is built from one exact snapshot, and regenerating from latest can surface additive changes you did not ask for on the day you least want them.

So generate from a pinned URL in CI:

curl -sS -o partner-api.yaml https://docs.valueverde.de/spec/1.6.0/partner-api.yaml

Every version we publish stays at its own URL permanently. /spec/index.json lists them, newest first, so a scheduled job can notice a new one and open a pull request rather than surprising a deploy:

{
  "name": "valueverde Partner API",
  "latest": "1.6.0",
  "versions": [
    {
      "version": "1.6.0",
      "yaml": "/spec/1.6.0/partner-api.yaml",
      "json": "/spec/1.6.0/partner-api.json",
      "aliases": ["/spec/partner-api.yaml", "/spec/partner-api.json"]
    },
    {
      "version": "1.5.0",
      "yaml": "/spec/1.5.0/partner-api.yaml",
      "json": "/spec/1.5.0/partner-api.json"
    }
  ]
}

What the document does not tell you

Two things are deliberately outside the schema, because they are runtime behaviour rather than shape:

• Rate limits. The headers are on every response; the numbers are in Rate limits.
• Idempotency. Idempotency-Key is declared on the endpoints that accept it, but the replay window and the conflict rule are in Investing flow.

Everything else — auth, scopes, every request and response shape, every error body, and the outbound webhook payloads under OpenAPI 3.1's top-level webhooks — is in the document.

If your reader is not a person

Increasingly the first thing to read an API's documentation is an assistant, and handing it a React shell to reverse-engineer helps nobody. The prose is published as Markdown too:

What	URL
Index of everything, llms.txt style	https://docs.valueverde.de/llms.txt
Every guide in one file	https://docs.valueverde.de/llms-full.txt
Any single page	append .md — e.g. /docs/quickstart.md

The endpoint reference is deliberately absent from those: the machine-readable form of an endpoint is the OpenAPI document above, and llms.txt points at it rather than paraphrasing it less precisely.