Projects and Knowledge

Project lifecycle

Create a Project from one public website URL. Analysis returns a profile, brand facts, competitors, exclusions, and a primary logo candidate. Review and confirm that profile before using Project Knowledge.

Project states are asynchronous. Poll the returned Project URL or use the SDK projects.wait() helper. Archiving a Project preserves prior Assets and Artifacts but disables future mutation and archives its active Loops.

• processing: analysis is still running.
• needs_review: confirm or correct the inferred profile.
• ready: Knowledge-backed work is available.
• failed or archived: inspect the canonical response before acting.

Sources and Collections

Sources are durable Project Knowledge. Add a URL, plain text, or multipart file; ingestion creates an immutable revision used by later Generations. Collections are optional organizational boundaries and selection filters.

For a file needed by only one request, set multipart keep_as_project_asset to false. The resulting request-only Source stays outside Collections and reusable Knowledge, expires after 24 hours if unclaimed, and is atomically claimed when an accepted Generation names it in top-level attachment_source_ids.

Remote Sources can be refreshed explicitly. Existing Generations keep their frozen Source revisions, so refreshes never rewrite work that is already accepted or in flight.

const source = await client.sources.create(project.id, {
  type: 'url',
  url: 'https://example.com/docs',
  title: 'Product documentation',
})

Select the right evidence

Use input.type: knowledge for reusable Project evidence, topic for an explicit subject optionally grounded in selected Sources, and trend for a bounded recent opportunity search. The API freezes the resolved context at acceptance.

Use top-level attachment_source_ids for up to 20 unique, ready Sources from the same Project that apply to this one preview and Generation. This is separate from input.source_ids: request-only uploads must be attached this way, while durable Project Sources remain reusable. Textual attachments can ground every Asset type; Product Visual attachments can guide Lead Magnets and Product Demo Videos only and do not replace textual grounding.