SOURCY / API REFERENCE / V1

Sourcing requests

Create a sourcing request, then update its items as the merchant makes their choices.

1. Choose your environment

Command examples for

Development is live. Production is not yet activated.

Server address: https://dev.ttk-agent.sourcy.ai
API base URL: https://dev.ttk-agent.sourcy.ai/api/v1
Create endpoint: https://dev.ttk-agent.sourcy.ai/api/v1/sourcing-requests

Use the complete endpoint in your requests. Opening / or /docs shows this page; /api/ alone is not an endpoint.

Set your token once

In your terminal, replace YOUR_API_TOKEN with the token shared by the team. Use the token for your selected environment. The commands below reuse this variable.

Terminal · bash / zsh

export API_TOKEN='YOUR_API_TOKEN'

Every API request needs Authorization: Bearer <token> and Content-Type: application/json. Both headers are included below. Never commit the real token or put it in frontend code.

2. Create a sourcing request

POST /api/v1/sourcing-requests → 201 Created

Required: external_id and merchant (both id and name). At signup you can omit items; it defaults to an empty list. This example creates two items.

Change external_id for each new request. Reusing the same merchant ID and external ID returns 409.

Complete cURL command

Loading example…

Save these values from the response

sr_id — public request ID, such as TTS-1. Use this in the update URL.
version — starts at 1. Send the latest returned version with every update.
items[].id — integer IDs for updating existing items. These are different from the SR ID.

The response is the saved SR object itself, including all items, defaults, IDs and timestamps.

3. Update the same sourcing request

PATCH /api/v1/sourcing-requests/{srId} → 200 OK

Replace TTS-1, version: 1 and item id: 1 below with values from your saved response. This example selects an item and changes its quantity and customization.

Complete cURL command

Loading example…

Omitted fields and items stay unchanged. Send at least one change plus version.
An item with an id updates it. An item without an ID adds a new item and needs name and description.
Supplied specs and images replace their arrays; use [] to clear them.
Supplied merchant, destination and customization replace the whole object. Use null only for nullable fields.
Each successful update returns the full SR with a new version. Save it for the next update.
Updates are atomic. If any item or version is invalid, nothing is saved. Items cannot be deleted through this API.