pipsync-api-collections

Dependency-free Postman and Bruno collections for the documented public PipSync REST API.

Important

This repository is intentionally read-only. It contains the unauthenticated health probe and every authenticated GET resource in the pinned public OpenAPI snapshot. It does not add write, webhook-ingress, broker, streaming, sandbox, or MCP endpoints.

Start in Postman

1. Import PipSync-Public-API.postman_collection.json.
2. Import either the hosted or synthetic-local environment from postman/.
3. For the hosted environment, set apiKey as a local/current secret value in Postman. Do not save it as a shared value.
4. Run Start here → Service health probe, then Authenticated user profile + tier.

A “Run in Postman” button is deliberately not embedded yet. A maintainer must first publish the collection to an official public workspace and replace the placeholder above with the verified URL; see docs/PUBLISHING.md. Importing the committed JSON works without that external listing.

Start in Bruno

1. Open the bruno/ directory as a collection.
2. Choose Hosted API.
3. Add apiKey through Bruno's secret-variable UI; the value is stored locally and is not committed.
4. Run Start here/01-health, then Start here/02-me.

Bruno inherits bearer authentication from collection.bru. The health request explicitly uses auth: none.

Run the completely local mock

Requires Node.js 20 or newer. The project has no runtime or development dependencies.

npm run mock

Then select PipSync Synthetic Local Mock in Postman or Local Mock in Bruno. The server:

• binds only to 127.0.0.1:4010
• makes no outbound network requests
• returns fixed, synthetic responses generated from the public response schemas
• accepts only the generated GET routes
• rejects the documented POST route with 405 Method Not Allowed
• uses the obvious sentinel synthetic-local-only, never a real API key
• marks every response with X-PipSync-Mock: synthetic-local-only

The hosted and local environments are separate. A Postman pre-request guard refuses to send the synthetic sentinel to the hosted base URL.

Included surface

Request	Authentication	Collection folder
GET /health	None	Start here
GET /me	Bearer API key	Start here
GET /account/usage	Bearer API key	Authenticated resources
GET /reports	Bearer API key	Authenticated resources
GET /reports/schedules	Bearer API key	Authenticated resources
GET /reports/trades	Bearer API key	Authenticated resources
GET /signals	Bearer API key	Authenticated resources
GET /trades	Bearer API key	Authenticated resources

POST /reports/schedules exists in the source contract but is excluded by the repository's read-only policy. The generated endpoint matrix is the reviewable source of truth.

Safe tests and examples

Each request checks that:

• its status code is documented by OpenAPI
• it did not return a server error
• the public health probe returned 200
• JSON responses parse when the response declares a JSON content type

Hosted authenticated requests can validly return documented 401, 403, or 429 responses, so the collection does not mislabel those contract outcomes as generator failures. Examples are schema-derived and visibly synthetic; they contain no user, account, signal, trade, or subscription data.

Deterministic generation

The pinned input is source/openapi.json, copied byte-for-byte from the sanitized public contract in pipsyncio/pipsync-spec. Its SHA-256 is recorded in provenance/source.json.

npm run generate          # regenerate both clients and provenance
npm run check:generated   # fail on generated-file drift
npm run check:source      # compare with a sibling pipsync-spec clone when present
npm test                  # all contract, drift, secret, and mock tests

The generator uses only Node.js built-ins. It fails closed if the hosted base URL, authentication scheme, public-operation boundary, excluded operation, or a security-sensitive path family changes.

Updating the contract

Do not hand-edit generated Postman, Bruno, endpoint-matrix, or provenance files. Instead:

1. review the released/sanitized change in pipsyncio/pipsync-spec
2. replace source/openapi.json with that reviewed snapshot
3. run npm run generate
4. inspect every diff, especially authentication and newly exposed paths
5. run npm test
6. record the change in CHANGELOG.md

Any new non-GET operation remains excluded. Any new public operation or path mentioning webhooks, brokers, streams, or MCP requires explicit security review rather than automatic publication.

Hosted PipSync access

The hosted API is separate from this open-source tooling and remains subject to its own access rules and terms. For authentication, scopes, rate limits, and product access, continue with the PipSync API reference.

Contributing, security, and license

See CONTRIBUTING.md, SECURITY.md, and docs/SAFETY.md. Never commit an API key, customer identifier, production response, signal, trade, email address, broker credential, private URL, or log excerpt.

Repository tooling and generated collection material are licensed under Apache-2.0; see LICENSE and NOTICE. The OpenAPI document retains its own info.license declaration. Postman and Bruno are third-party products and trademarks of their respective owners.

Trading involves risk. This repository is developer tooling, not financial advice and not a promise of execution quality or returns.