picked 0.0.101-next.2 → 0.0.101

package/docs/reference/management-api/schema/project.md

@@ -0,0 +1,607 @@
+---
+type: reference
+layout: docs
+generated: true
+---
+
+# Project schema
+
+The operations and types that `project.graphql` adds to the Management API. See [Management API schema](/reference/management-api/schema) for every domain, the endpoint and authentication.
+
+## Queries
+
+### `project`
+
+Fetch a single project by ID. Requires authentication.
+
+```graphql
+project(input: ProjectInput!): Project @auth
+```
+
+### `projects`
+
+List projects the authenticated user can reach, across every organisation they
+belong to. Pass `organizationId` to narrow the list to one organisation, and
+`search` to match project names case-insensitively. Requires authentication.
+
+```graphql
+projects(organizationId: ID, first: Int, after: String, search: String, sortKey: ProjectSortKeys = NAME, reverse: Boolean = false): ProjectConnection! @auth
+```
+
+## Mutations
+
+### `projectCreate`
+
+Create a new project. Requires scope: `ORGANIZATION_PROJECTS_CREATE`.
+
+```graphql
+projectCreate(input: ProjectCreateInput!): ProjectCreatePayload! @auth
+```
+
+### `projectUpdate`
+
+Update a project. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`.
+
+```graphql
+projectUpdate(input: ProjectUpdateInput!): ProjectUpdatePayload! @auth
+```
+
+### `projectDelete`
+
+Delete a project. Requires scope: `ORGANIZATION_PROJECTS_DELETE`.
+
+```graphql
+projectDelete(input: ProjectDeleteInput!): ProjectDeletePayload! @auth
+```
+
+### `projectPreviewEnvironmentCreate`
+
+Create a project preview environment. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`.
+
+```graphql
+projectPreviewEnvironmentCreate(input: ProjectPreviewEnvironmentCreateInput!): ProjectPreviewEnvironmentCreatePayload! @auth
+```
+
+### `projectPreviewEnvironmentUpdate`
+
+Update a project preview environment. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`.
+
+```graphql
+projectPreviewEnvironmentUpdate(input: ProjectPreviewEnvironmentUpdateInput!): ProjectPreviewEnvironmentUpdatePayload! @auth
+```
+
+### `projectPreviewEnvironmentDelete`
+
+Delete a project preview environment. Requires scope: `ORGANIZATION_PROJECTS_UPDATE`.
+
+```graphql
+projectPreviewEnvironmentDelete(input: ProjectPreviewEnvironmentDeleteInput!): ProjectPreviewEnvironmentDeletePayload! @auth
+```
+
+## Types
+
+### `ProjectSortKeys`
+
+```graphql
+"""
+Sort keys accepted by `Organization.projects(...)`. Pair with `reverse: true`
+to flip the order.
+"""
+enum ProjectSortKeys {
+  """Sort by project `name` (alphabetical)."""
+  NAME
+  """Sort by `createdAt`."""
+  CREATED_AT
+  """
+  Sort by `updatedAt`. Pair with `reverse: true` for most-recently-changed first.
+  """
+  UPDATED_AT
+}
+```
+
+### `WorkspaceSortKeys`
+
+```graphql
+"""
+Sort keys accepted by `Project.workspaces(...)`. Pair with `reverse: true`
+to flip the order.
+
+`DRAFT_CHANGED_AT` orders by the last draft content change, which is what
+"most recently worked on" means for a workspace; `Workspace` carries no
+`updatedAt`.
+"""
+enum WorkspaceSortKeys {
+  """Sort by workspace `name` (alphabetical)."""
+  NAME
+  """Sort by `createdAt`."""
+  CREATED_AT
+  """Sort by `draftChangedAt`."""
+  DRAFT_CHANGED_AT
+}
+```
+
+### `Project`
+
+```graphql
+"""
+A project — an isolated A/B testing surface under an organisation.
+
+Projects own workspaces (DRAFT / LIVE / ARCHIVED), CMS content, reports,
+and integrations. `LIVE` is derived, not stored. At most one workspace is
+live at a time (the one owning the project's served version), and
+`liveWorkspaceVersion` exposes that currently-published immutable snapshot
+(null until the first publish).
+
+The `timezone` field anchors analytics aggregations (e.g. "yesterday")
+and is immutable after creation.
+"""
+type Project {
+  """Unique project identifier."""
+  id: ID!
+  """Display name of the project."""
+  name: String!
+  """ID of the organisation this project belongs to."""
+  organizationId: ID!
+  """When this project was created."""
+  createdAt: DateTime!
+  """When this project was last updated."""
+  updatedAt: DateTime!
+  """
+  IANA timezone identifier used for analytics aggregations (e.g. `America/New_York`). Immutable after creation.
+  """
+  timezone: String
+  """
+  Author-provided markdown brief (audience, tone, goals, value props, entry points). Read by the Picked AI agents. Null until set.
+  """
+  context: String
+  """The organisation this project belongs to."""
+  organization: Organization!
+  """Configuration settings for this project (key/value pairs)."""
+  settings: [ProjectSetting!]!
+  """
+  SDK presence recorded against this project, or null when none was ever recorded.
+  """
+  sdkPresence: SdkPresence @deprecated(reason: "No SDK version records presence. Reads frozen rows; will be removed.")
+  """
+  The workspace that owns the project's currently-served version, or null if
+  the project has never been published. Requires authentication.
+  """
+  liveWorkspace: Workspace @auth
+  """
+  The version this project currently serves (resolved through
+  `projects.live_workspace_version_id`), or null if no workspace has been
+  published yet. After a rollback this may be an earlier version, not the
+  most recently published one. The snapshot's `config_json` blob is
+  intentionally not exposed. Use `workspaceDiff` to read its contents.
+  Requires authentication.
+  """
+  liveWorkspaceVersion: WorkspaceVersion @auth
+  """
+  Every published version across all of the project's workspaces, ordered
+  newest-first by `publishedAt`. This is the project-wide rollback history:
+  each version carries the `workspace` it was published from, and the one
+  matching `liveWorkspaceVersion` is the currently-served version. Versions
+  owned by a soft-deleted workspace are excluded. Supports forward
+  (`first`/`after`) and backward (`last`/`before`) pagination with stable
+  cursors over `(publishedAt, id)`. Requires authentication.
+  """
+  workspaceVersions(first: Int, after: String, last: Int, before: String): WorkspaceVersionConnection! @auth
+  """
+  Workspaces belonging to this project. Filter by name with `search`
+  (case-insensitive substring) and by status with `status`, which keeps
+  workspaces holding any of the listed statuses and applies to `totalCount`
+  too. `HIDDEN` matches nothing, since snapshots never appear here. Requires
+  authentication.
+  """
+  workspaces(first: Int, after: String, last: Int, before: String, search: String, status: [WorkspaceStatus!], sortKey: WorkspaceSortKeys = CREATED_AT, reverse: Boolean = false): WorkspaceConnection! @auth
+  """Reports associated with this project. Requires authentication."""
+  reports(first: Int, after: String, sortKey: ReportSortKeys = NAME, reverse: Boolean = false): ProjectReportConnection! @auth
+  """All integrations installed for this project. Requires authentication."""
+  integrations: [Integration!]! @auth
+  """
+  A specific integration by type, or null if not installed. Requires authentication.
+  """
+  integration(type: IntegrationType!): Integration @auth
+  """
+  Third-party MCP servers registered to this project. Requires authentication.
+  """
+  mcpServers(first: Int, after: String): McpServerConnection! @auth
+  """
+  External APIs registered to this project — the origins its workflows may call. Requires authentication.
+  """
+  externalApis(first: Int, after: String): ExternalApiConnection! @auth
+  """
+  The project's own labels, ordered by namespace then key: state a workflow or a
+  person keeps for the whole project, such as a counter or a lock. An expired
+  label is not listed. Project labels outlive every lead. Write them with `labelsSet`, `ownerType: PROJECT` and the
+  project's id. Requires scope: `ORGANIZATION_PROJECTS_READ`.
+  """
+  labels: [Label!]! @auth
+  """
+  Leads captured by this project, newest first by default. Requires scope: `ORGANIZATION_LEADS_READ`.
+  """
+  leads(
+    first: Int
+    after: String
+    last: Int
+    before: String
+    """
+    A leads search query: a bare word matches the captured responses, and
+    `<namespace>.<key>`, a field key, `createdAt`, `userId`, or `session.<field>`
+    addresses a label, a response, the capture time, the visitor, or the session
+    the lead was captured in. See
+    https://docs.picked.app/reference/dashboard/lead-search.
+    """
+    query: String
+    """
+    The path to order by, in the same grammar `query` uses:
+    `labels.<namespace>.<key>`, `responses.<key>`, or `id`, `userId`,
+    `createdAt`. A path naming nothing sortable orders by capture time, so a
+    hand-edited URL degrades rather than fails. Leads carrying no value at the
+    path sort last in either direction. A query with a `session.` clause lists
+    its leads by their capture events, newest first unless `reverse` is false,
+    and takes either no sort or `createdAt`; any other sort is a validation error.
+    """
+    sort: String
+    reverse: Boolean = true
+    """
+    Narrows the leads to those captured inside this window, in the project's
+    time zone. `totalCount` and `metrics` count under the same window, and a
+    metric measures over it unless given its own.
+    """
+    window: MetricWindowInput
+    """
+    How the leads captured under one SDK session id read. `SESSION` lists each
+    session's newest matching lead alone, and `matchCount` and `metrics` count
+    sessions. A query with a `session.` clause takes `NONE` alone.
+    """
+    collapse: LeadCollapse = NONE
+  ): LeadConnection! @auth
+  """
+  The Leads reports on this project, in order: how leads are
+  acquired, the journeys behind them, and how visits convert to leads. Each is
+  a signed guest embed URL with the project locked and the date range left
+  editable, read from the project's analytics warehouse. Requires scope:
+  `ORGANIZATION_LEADS_READ` or `ORGANIZATION_REPORTS_READ`.
+  """
+  leadReports: [LeadReport!]! @auth
+  """
+  The Sessions reports on this project, in order: how its sessions arrive, the
+  journeys they take, and which of them convert. Each is a signed guest embed URL
+  with the project locked and the date range left editable, read from the
+  project's analytics warehouse. Requires scope: `ORGANIZATION_LEADS_READ`.
+  """
+  analyticsSessionsReports: [AnalyticsSessionsReport!]! @auth
+  """
+  One visitor session on this project's sites, read from the project's analytics
+  warehouse across all of its events, anchored on its latest lead capture, else on
+  its latest timeline event. Null when the warehouse holds no event of it. Requires
+  scope: `ORGANIZATION_LEADS_READ`.
+  """
+  analyticsSession(
+    """The identity resolver's session identifier."""
+    id: ID!
+  ): AnalyticsSession @auth
+  """
+  Visitor sessions on this project's sites, newest first by when they started, read
+  from the project's analytics warehouse. A session is its events inside `window`,
+  so one that began before the window starts at its first event inside it, and its
+  `summary` adds up those events alone. Pages by keyset: `first` and `after` read
+  older sessions, `last` and `before` newer ones; a page holds at most 100. The
+  newest events can take a few minutes to arrive. Requires scope:
+  `ORGANIZATION_LEADS_READ`.
+  """
+  analyticsSessions(
+    first: Int
+    after: String
+    last: Int
+    before: String
+    """
+    The window the sessions' events fall inside, in the project's time zone.
+    Defaults to today and the six days before it.
+    """
+    window: MetricWindowInput
+    """
+    The sessions to keep, in the session search query language: the leads
+    search grammar over a session. A bare word is a case-insensitive substring
+    of a URL the session visited or landed on; `<field>:value`, `<field>~value`
+    and `<field>:*` ask that some event of the session holds the value, a value
+    containing it, or any value, for `gaid`, `utm_source`, `utm_medium`,
+    `utm_campaign`, `utm_term`, `utm_content`, `page_url`, `page_origin`,
+    `page_pathname`, `page_query`, `landing_page_url`, `landing_page_origin`,
+    `landing_page_pathname` or `landing_page_query`, each also written under
+    `session.`; `lead:*` asks that the session captured a lead. A leading `-`
+    negates a clause; clauses combine with AND, or with OR when the query says
+    so, never both; at most ten.
+    """
+    query: String
+    """
+    Whether to keep the sessions of bots. A session is a bot's when one of its events
+    inside the window ran on a device the user agent names as a crawler, scanner or
+    scripted browser: a robot, hacker or spy device class, or a headless Chrome or
+    Lighthouse agent. Left out by default, from the page and from `metrics` alike.
+    """
+    includeBots: Boolean = false
+  ): AnalyticsSessionConnection! @auth
+  """
+  Saved views of one of this project's lists, oldest first. Requires scope:
+  `ORGANIZATION_PROJECTS_READ`.
+  """
+  savedViews(
+    """Which list to read the views of."""
+    resource: SavedViewResource!
+    first: Int
+    after: String
+    last: Int
+    before: String
+  ): SavedViewConnection! @auth
+  """
+  Customer-site URLs registered for embedding CMS page previews, ordered by `createdAt` ascending.
+  """
+  previewEnvironments: [ProjectPreviewEnvironment!]!
+}
+```
+
+### `ProjectPreviewEnvironment`
+
+```graphql
+"""
+A customer-installed SDK URL (Production, Staging, etc.) used by the page-preview iframe.
+"""
+type ProjectPreviewEnvironment {
+  id: ID!
+  """Human-readable label (e.g. 'Production', 'Staging'). 1-40 characters."""
+  label: String!
+  """
+  Origin or URL where the SDK is installed; the dashboard appends `?picked-preview-token=<token>`.
+  """
+  url: String!
+}
+```
+
+### `ProjectPreviewEnvironmentErrorCode`
+
+```graphql
+"""
+Validation error code returned by the projectPreviewEnvironment* mutations.
+"""
+enum ProjectPreviewEnvironmentErrorCode {
+  PROJECT_NOT_FOUND
+  ENVIRONMENT_NOT_FOUND
+  LABEL_REQUIRED
+  LABEL_TOO_LONG
+  URL_REQUIRED
+  URL_INVALID
+}
+```
+
+### `ProjectPreviewEnvironmentUserError`
+
+```graphql
+"""
+User-facing validation error returned by the projectPreviewEnvironment* mutations.
+"""
+type ProjectPreviewEnvironmentUserError {
+  """Path to the offending input field, e.g. ['label']."""
+  field: [String!]
+  """Human-readable message suitable for display."""
+  message: String!
+  """Machine-readable error code."""
+  code: ProjectPreviewEnvironmentErrorCode!
+}
+```
+
+### `ProjectPreviewEnvironmentCreateInput`
+
+```graphql
+"""Input for creating a project preview environment."""
+input ProjectPreviewEnvironmentCreateInput {
+  projectId: ID!
+  label: String!
+  url: String!
+}
+```
+
+### `ProjectPreviewEnvironmentCreatePayload`
+
+```graphql
+"""Payload returned by `projectPreviewEnvironmentCreate`."""
+type ProjectPreviewEnvironmentCreatePayload {
+  """The created environment, or null when input failed validation."""
+  environment: ProjectPreviewEnvironment
+  """Per-field validation errors; empty on success."""
+  userErrors: [ProjectPreviewEnvironmentUserError!]!
+}
+```
+
+### `ProjectPreviewEnvironmentUpdateInput`
+
+```graphql
+"""Input for updating a project preview environment."""
+input ProjectPreviewEnvironmentUpdateInput {
+  id: ID!
+  label: String!
+  url: String!
+}
+```
+
+### `ProjectPreviewEnvironmentUpdatePayload`
+
+```graphql
+"""Payload returned by `projectPreviewEnvironmentUpdate`."""
+type ProjectPreviewEnvironmentUpdatePayload {
+  """The updated environment, or null when input failed validation."""
+  environment: ProjectPreviewEnvironment
+  """Per-field validation errors; empty on success."""
+  userErrors: [ProjectPreviewEnvironmentUserError!]!
+}
+```
+
+### `ProjectPreviewEnvironmentDeleteInput`
+
+```graphql
+"""Input for deleting a project preview environment."""
+input ProjectPreviewEnvironmentDeleteInput {
+  id: ID!
+}
+```
+
+### `ProjectPreviewEnvironmentDeletePayload`
+
+```graphql
+"""Payload returned by `projectPreviewEnvironmentDelete`."""
+type ProjectPreviewEnvironmentDeletePayload {
+  """
+  ID of the deleted environment, or null when the input failed validation.
+  """
+  deletedEnvironmentId: ID
+  """Per-field validation errors; empty on success."""
+  userErrors: [ProjectPreviewEnvironmentUserError!]!
+}
+```
+
+### `ProjectSetting`
+
+```graphql
+"""
+A single key/value setting on a project. The shape of `value` depends on
+`key`; well-known keys are documented in the dashboard. Free-form keys
+are allowed for use by integrations and the SDK plugin system.
+"""
+type ProjectSetting {
+  """Setting key. Stable across SDK versions."""
+  key: String!
+  """Setting value as a JSON value. Shape depends on the key."""
+  value: JSON!
+}
+```
+
+### `SdkPresence`
+
+```graphql
+"""
+SDK presence recorded against a project. The rows are frozen: `lastSeenAt`
+reports the last boot recorded while presence tracking was live, so it answers
+"when did this project last report in", not "is the SDK reaching us now".
+"""
+type SdkPresence {
+  """ID of the project this presence belongs to."""
+  projectId: ID!
+  """When the SDK was last seen booting."""
+  lastSeenAt: DateTime
+  """Always null."""
+  sdkVersion: String
+  """Always null."""
+  environment: String
+}
+```
+
+### `ProjectEdge`
+
+```graphql
+"""Edge type for `ProjectConnection`."""
+type ProjectEdge {
+  """Pagination cursor for this edge."""
+  cursor: String!
+  """The project."""
+  node: Project!
+}
+```
+
+### `ProjectConnection`
+
+```graphql
+"""Relay-style connection of projects."""
+type ProjectConnection {
+  """List of project edges."""
+  edges: [ProjectEdge!]!
+  """Pagination metadata."""
+  pageInfo: PageInfo!
+  """Total number of projects."""
+  totalCount: Int!
+}
+```
+
+### `ProjectInput`
+
+```graphql
+"""Input for looking up a single project."""
+input ProjectInput {
+  """Project ID to look up."""
+  id: ID!
+}
+```
+
+### `ProjectCreateInput`
+
+```graphql
+"""Input for `projectCreate`."""
+input ProjectCreateInput {
+  """Name of the project."""
+  name: String!
+  """ID of the organisation to create the project in."""
+  organizationId: ID!
+  """
+  IANA timezone identifier for analytics and reporting (e.g. `America/New_York`). Cannot be changed after creation.
+  """
+  timezone: String!
+}
+```
+
+### `ProjectCreatePayload`
+
+```graphql
+"""Payload returned by `projectCreate`."""
+type ProjectCreatePayload {
+  """The newly created project."""
+  project: Project
+}
+```
+
+### `ProjectUpdateInput`
+
+```graphql
+"""
+Input for `projectUpdate`. Only mutable fields are accepted — `timezone` is immutable.
+"""
+input ProjectUpdateInput {
+  """ID of the project to update."""
+  id: ID!
+  """New name for the project. Omit to leave unchanged."""
+  name: String
+  """
+  New markdown context brief. Omit to leave unchanged; pass an empty string to clear.
+  """
+  context: String
+}
+```
+
+### `ProjectUpdatePayload`
+
+```graphql
+"""Payload returned by `projectUpdate`."""
+type ProjectUpdatePayload {
+  """The updated project."""
+  project: Project
+}
+```
+
+### `ProjectDeleteInput`
+
+```graphql
+"""Input for `projectDelete`."""
+input ProjectDeleteInput {
+  """ID of the project to delete."""
+  id: ID!
+}
+```
+
+### `ProjectDeletePayload`
+
+```graphql
+"""Payload returned by `projectDelete`."""
+type ProjectDeletePayload {
+  """ID of the deleted project."""
+  deletedProjectId: ID
+}
+```