{"openapi":"3.1.0","info":{"title":"SourceFoundry API","version":"1 (83c074d731b61522f1b354b1549b8f4e4be0412c)","description":"Recurring source feeds, fresh source items, and source-health reporting for agents."},"servers":[{"url":"https://sourcefoundry.4agents.fyi","description":"Canonical SourceFoundry service"}],"security":[{"bearerAuth":[]}],"paths":{"/health":{"get":{"summary":"Process liveness","description":"Returns public service identity and release.","responses":{"200":{"description":"Successful response"},"202":{"description":"Accepted for processing"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/Error"}},"security":[]}},"/ready":{"get":{"summary":"Service readiness","description":"Returns readiness after a database connectivity check.","responses":{"200":{"description":"Successful response"},"202":{"description":"Accepted for processing"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/Error"}},"security":[]}},"/v1/meta":{"get":{"summary":"Discover agent capabilities","description":"Returns the supported agent workflow and authentication boundary.","responses":{"200":{"description":"Successful response"},"202":{"description":"Accepted for processing"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/Error"}},"security":[]}},"/llms.txt":{"get":{"summary":"Read the agent guide","description":"A machine-discoverable alias for the SourceFoundry agent guide.","responses":{"200":{"description":"Successful response"},"202":{"description":"Accepted for processing"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/Error"}},"security":[]}},"/v1/agent-enrollments":{"post":{"summary":"Create an autonomous workspace","description":"Creates a tenant-scoped credential and returns its secret exactly once. No authentication is required.","responses":{"201":{"description":"Workspace and one-time agent credential created."},"400":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"}},"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["slug","name"],"properties":{"slug":{"type":"string","pattern":"^[a-z0-9][a-z0-9-]{1,61}[a-z0-9]$","example":"acme-research"},"name":{"type":"string","example":"Acme Research"},"agentLabel":{"type":"string","example":"research-agent"}}}}}}}},"/v1/tenants":{"post":{"summary":"Upsert a tenant","description":"Safe to repeat for the same slug.","responses":{"200":{"description":"Successful response"},"202":{"description":"Accepted for processing"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/Error"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["slug","name"],"properties":{"slug":{"type":"string","example":"acme-research"},"name":{"type":"string","example":"Acme Research"},"config":{"type":"object","additionalProperties":true}}}}}}}},"/v1/source-feeds":{"post":{"summary":"Build a durable source feed","description":"Creates or updates a recurring source-supply contract. Requires an Idempotency-Key header. Autonomous credentials infer their tenant; operator credentials provide tenantId.","responses":{"200":{"description":"Successful response"},"202":{"description":"Accepted for processing"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","maxLength":200}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","purpose","sources","cadence"],"properties":{"tenantId":{"type":"string","format":"uuid","description":"Required only for operator credentials."},"name":{"type":"string","maxLength":160},"purpose":{"type":"string","maxLength":2000},"sources":{"type":"array","minItems":1,"items":{"type":"object","required":["kind","label"],"properties":{"kind":{"type":"string","enum":["feed","discovery"]},"label":{"type":"string"},"url":{"type":"string","format":"uri","description":"Required for feed sources."},"provider":{"type":"string","enum":["tavily","exa","serper"],"default":"tavily","description":"Search provider for a discovery source. Self-hosted operators supply the matching key through the worker environment."},"required":{"type":"boolean"},"queries":{"type":"array","items":{"type":"string"},"description":"Required for discovery sources."},"includeDomains":{"type":"array","items":{"type":"string"}},"excludeDomains":{"type":"array","items":{"type":"string"}}}}},"cadence":{"type":"object","required":["everyMinutes"],"properties":{"everyMinutes":{"type":"integer","minimum":5,"maximum":10080}}},"limits":{"type":"object","properties":{"maxItemsPerRun":{"type":"integer","minimum":1,"maximum":100,"default":20},"maxCandidatesPerRun":{"type":"integer","minimum":1,"maximum":100,"default":10}}}}}}}}}},"/v1/source-feeds/{sourceFeedId}/runs":{"post":{"summary":"Run a source feed now","description":"Fans out into the existing bounded source jobs and reuses an active feed run on retry.","responses":{"200":{"description":"Successful response"},"202":{"description":"Accepted for processing"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"sourceFeedId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}]}},"/v1/source-feeds/{sourceFeedId}/candidates":{"get":{"summary":"Read source-feed candidates","description":"Returns the existing neutral PublicSignal contract, scoped to this feed.","responses":{"200":{"description":"Successful response"},"202":{"description":"Accepted for processing"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"sourceFeedId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"since","in":"query","schema":{"type":"string","format":"date-time"}},{"name":"statuses","in":"query","schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100}}]}},"/v1/source-feeds/{sourceFeedId}/health":{"get":{"summary":"Inspect source-feed health","description":"Returns feed-specific source failures, latest run state, and candidate freshness.","responses":{"200":{"description":"Successful response"},"202":{"description":"Accepted for processing"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"sourceFeedId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}]}},"/v1/source-feed-runs/{runId}":{"get":{"summary":"Inspect a source-feed run","description":"Derives the feed-run state from its existing durable source jobs.","responses":{"200":{"description":"Successful response"},"202":{"description":"Accepted for processing"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"runId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}]}},"/v1/sources":{"get":{"summary":"List a tenant’s sources","description":"Provide exactly one tenant or tenantId query parameter.","responses":{"200":{"description":"Successful response"},"202":{"description":"Accepted for processing"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"tenant","in":"query","schema":{"type":"string","example":"acme-research"}},{"name":"tenantId","in":"query","schema":{"type":"string","format":"uuid"}}]},"post":{"summary":"Upsert a source","description":"Safe to repeat for the same tenant and canonical source URL. Configure provider intent in metadata; never provide provider credentials.","responses":{"200":{"description":"Successful response"},"202":{"description":"Accepted for processing"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/Error"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["tenantId","name","sourceType","url"],"properties":{"tenantId":{"type":"string","format":"uuid"},"name":{"type":"string","example":"AI policy discovery"},"sourceType":{"type":"string","enum":["rss","atom","web"]},"url":{"type":"string","format":"uri","example":"https://api.tavily.com/search"},"reliability":{"type":"number","minimum":0,"maximum":1,"default":0.7},"intervalMinutes":{"type":"integer","minimum":1,"maximum":10080,"default":60},"maxItemsPerFetch":{"type":"integer","minimum":1,"maximum":100,"default":30},"timeoutSeconds":{"type":"integer","minimum":1,"maximum":300,"default":20},"metadata":{"type":"object","description":"Provider-neutral source policy, such as mode, provider, queries, and domain filters. Do not include secrets.","additionalProperties":true}}}}}}}},"/v1/sources/{sourceId}":{"get":{"summary":"Get one source","description":"Returns stored source configuration and health counters.","responses":{"200":{"description":"Successful response"},"202":{"description":"Accepted for processing"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"sourceId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}]}},"/v1/ingest/source":{"post":{"summary":"Enqueue a source fetch","description":"Returns an existing active job rather than creating duplicate work.","responses":{"200":{"description":"Successful response"},"202":{"description":"Accepted for processing"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/Error"}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["tenantId","sourceId"],"properties":{"tenantId":{"type":"string","format":"uuid"},"sourceId":{"type":"string","format":"uuid"},"priority":{"type":"integer","minimum":-100,"maximum":100,"default":0}}}}}}}},"/v1/jobs/{jobId}/run-once":{"post":{"summary":"Run one queued job now","description":"This may trigger a provider request. Use only with an explicit request for immediate execution.","responses":{"200":{"description":"Successful response"},"202":{"description":"Accepted for processing"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"jobId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}]}},"/v1/signals":{"get":{"summary":"Read normalized evidence","description":"Returns the versioned, provider-neutral signal contract.","responses":{"200":{"description":"Successful response"},"202":{"description":"Accepted for processing"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Unauthorized"},"500":{"$ref":"#/components/responses/Error"}},"parameters":[{"name":"tenant","in":"query","schema":{"type":"string","example":"acme-research"}},{"name":"tenantId","in":"query","schema":{"type":"string","format":"uuid"}},{"name":"statuses","in":"query","schema":{"type":"string","example":"published,approved"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}}]}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API token"}},"responses":{"Unauthorized":{"description":"A valid SourceFoundry API token is required."},"Error":{"description":"Versioned error response with code and retryable flag."}}}}