Sources

A source (src_…) is one connection to a vendor's data: where it comes from, how it is read, how often, and why FurniOps may use it. Every pull of a source is a run, and what the runs read becomes your catalogue's master records.

{
  "object": "source",
  "id": "src_034XqBaL2mRLTZPXyRbaUc",
  "catalogue": "cat_034XqBaL2mRLTZPXyRbaUa",
  "name": "Coaster dealer API",
  "kind": "api",
  "connector": "coaster",
  "config": { "warehouse": "TX" },
  "schedule": { "interval_minutes": 1440, "stock_interval_minutes": 30 },
  "status": "degraded",
  "status_reason": {
    "code": "credentials",
    "message": "The source refused the stored credentials."
  },
  "licence_basis": "tenant_account",
  "has_credentials": true,
  "freshness": {
    "catalogue": {
      "interval_minutes": 1440,
      "changes_per_day": 0.8,
      "observations": 21,
      "learned_at": "2026-10-06T07:00:12Z"
    },
    "stock": {
      "interval_minutes": 30,
      "changes_per_day": 36,
      "observations": 412,
      "learned_at": "2026-10-06T09:00:40Z"
    }
  },
  "inbound_address": null,
  "version": 7,
  "created_at": "2026-09-14T15:02:11Z",
  "updated_at": "2026-10-06T09:00:40Z"
}

What FurniOps can read todayCopy Anchor Link

A source FurniOps cannot run yet is kept: the schedule passes it by, and starting a run answers 422. Connectors covers the Shopify feed and Coaster in detail.

Create a sourceCopy Anchor Link

// A vendor's price list at a URL, read every 6 hours.
const pricelist = await furniops.sources.create({
  name: "Acme price list",
  kind: "file",
  config: { url: "https://vendor.example/feeds/pricelist.csv", format: "csv", role: "supplier" },
  schedule: { interval_minutes: 360 },
  licence_basis: "vendor_agreement",
});
console.log(pricelist.id, pricelist.status); // "src_…", "active"

A field that does not fit the kind answers 422 with the field named: a feed needs url and platform, an api source needs a connector, and warehouse, price_code and inbound apply to one kind each.

ConfigCopy Anchor Link

Licence basisCopy Anchor Link

Every source says why FurniOps may use its data. It is your statement, and it decides how the data may be shared (see Licences):

CredentialsCopy Anchor Link

A source that signs in to a vendor (an api source) needs credentials. Set them apart from the source, with PUT /v1/sources/{id}/credentials: named values such as api_key, up to 16. They are sealed under the source's ID as they arrive and never returned: the source shows only has_credentials. Setting them again replaces them all; DELETE forgets them, and runs that need them then fail as credentials.

// Coaster's dealer API: the catalogue once a day, stock every 30 minutes.
const coaster = await furniops.sources.create({
  name: "Coaster dealer API",
  kind: "api",
  connector: "coaster",
  config: { warehouse: "TX" },
  schedule: { interval_minutes: 1440, stock_interval_minutes: 30 },
  licence_basis: "tenant_account",
});
// Write-only: sealed as it arrives, never returned. The source shows has_credentials: true.
await furniops.sources.setCredentials(coaster.id, { values: { api_key: "…" } });
const test = await furniops.sources.test(coaster.id);
console.log(test.ok, test.http_status, test.detail);

Test a sourceCopy Anchor Link

POST /v1/sources/{id}/test reaches the source once, as a run would, and reports what it answered: whether it gave data, the HTTP status, the content type, the time to the response headers, and why it failed. Nothing is stored. A source fetched from a URL is asked for it; an api source's connector signs in with the stored credentials. A file source without a URL has nothing to reach and answers 422.

ScheduleCopy Anchor Link

How FurniOps learns a source's rhythm, and how to have it check what matters now, is in Freshness.

Change a sourceCopy Anchor Link

PATCH /v1/sources/{id} changes the name, connector, config (replaced whole), schedule, status or licence basis; the kind is fixed. Send the ETag you read as If-Match (optimistic concurrency).

Status and healthCopy Anchor Link

FurniOps judges a source by how its runs end. Only the source's own failures count: a run that failed for any reason but an internal error. A success resets the count; a run that needs a mapping or was aborted changes nothing.

• Degraded after 3 failures in a row.
• Blocked when a degraded source has kept failing for 14 days, after 100 failures in a row, or at once when its URL is refused (a private address or a scheme FurniOps will not fetch), since no retry can pass until the URL changes.
• Recovered to active by its next successful run, while degraded.

status_reason holds the run error behind a degraded or blocked verdict. Setting the status yourself clears it: to unblock a source, fix the cause (the URL, the credentials) and set it active.

Each verdict is an event, delivered by webhooks, the change feed and the stream, with the full source:

Before you add a sourceCopy Anchor Link

Not sure what a vendor's site offers? A probe reads it politely and reports the platform, any public feed and the effort to pull it.