> ## Documentation Index
> Fetch the complete documentation index at: https://docs.erdo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# SetWorkstreamExternalRefsAPI declares which provider-owned objects a workstream
governs, the


> machine-readable replacement for a campaign allowlist typed into a knowledge record. It is REST only with no MCP mirror, deliberately: an agent must be able to read the set of live campaigns it may act on and must not be able to widen it. The consumer holding the mapping declares scope here and agents read it back on every workstream and ledger read.




## OpenAPI

````yaml /api/openapi.json put /v1/workstreams/{workstreamSlug}/external-refs
openapi: 3.0.0
info:
  title: Erdo API
  description: >-
    Erdo's REST API: query and write datasets, run agents, manage threads,
    integrations, pages, evals, workstreams, experiments, and bounded outreach.
    Authenticate with a Bearer API key (erdo_api_...) or scoped token
    (erdo_token_...).
  version: '2026-11-21'
servers:
  - url: https://api.erdo.ai
    description: Production
security:
  - bearerAuth: []
paths:
  /v1/workstreams/{workstreamSlug}/external-refs:
    put:
      summary: >
        SetWorkstreamExternalRefsAPI declares which provider-owned objects a
        workstream

        governs, the
      description: >
        machine-readable replacement for a campaign allowlist typed into a
        knowledge record. It is REST only with no MCP mirror, deliberately: an
        agent must be able to read the set of live campaigns it may act on and
        must not be able to widen it. The consumer holding the mapping declares
        scope here and agents read it back on every workstream and ledger read.
      operationId: PUT:mcp.SetWorkstreamExternalRefsAPI
      parameters:
        - allowEmptyValue: true
          explode: false
          in: path
          name: workstreamSlug
          required: true
          schema:
            type: string
          style: simple
      requestBody:
        content:
          application/json:
            schema:
              properties:
                expected_revision:
                  description: >
                    writer that read the workstream before deciding the set. nil
                    is unconditional. Same contract as UpdateWorkStateRequest.
                  format: int64
                  title: >
                    ExpectedRevision is the revision this scope was resolved
                    against, for a
                  type: integer
                external_refs:
                  items:
                    $ref: '#/components/schemas/types.ExternalRef'
                  type: array
              type: object
      responses:
        '200':
          content:
            application/json:
              schema:
                properties:
                  assignments:
                    description: >
                      coordinator and Studio. It carries responsibility,
                      execution, submission, and adoption as separate facts;
                      callers must not infer work state from an agent transcript
                      or collapse a proposed result into an accepted one.
                    items:
                      $ref: '#/components/schemas/types.AssignmentSummary'
                    title: >
                      Assignments is the bounded durable-work projection used by
                      both the
                    type: array
                  current_decisions:
                    description: >
                      agent receives, on the same read: standing commitments and
                      in-flight authorizations, then the history around them.
                      The operator returning to a workstream and the agent
                      continuing it are answering the same question — what are
                      we operating under? — and a detail page that had to derive
                      its own answer would be a second copy free to disagree
                      with the one steering the work.
                    items:
                      $ref: '#/components/schemas/types.DecisionSummary'
                    title: >
                      CurrentDecisions / RecentDecisions are the same projection
                      the reconciling
                    type: array
                  events:
                    description: >
                      (newest first), embedded so cards/agents see activity
                      without a second call.
                    items:
                      $ref: '#/components/schemas/types.WorkstreamEvent'
                    title: >
                      Events is the most recent slice of the workstream's
                      chronological log
                    type: array
                  lapsed_decisions:
                    items:
                      $ref: '#/components/schemas/types.DecisionSummary'
                    type: array
                  recent_decisions:
                    items:
                      $ref: '#/components/schemas/types.DecisionSummary'
                    type: array
                  resources:
                    items:
                      $ref: '#/components/schemas/types.WorkstreamResource'
                    type: array
                  workstream:
                    $ref: '#/components/schemas/types.Workstream'
                type: object
          description: Success response
        default:
          $ref: '#/components/responses/APIError'
components:
  schemas:
    types.ExternalRef:
      description: >
        \`workstream\_resource\` cannot express this (it keys on a uuid, and
        providers do not issue them: a Google Ads campaign is \`24033607833\`),
        so scope used to live in prose hand-mirrored from a mapping the job
        could not see. Every field is an opaque provider string: Erdo does not
        parse, validate against the provider or dereference them, and stores
        what the owning consumer resolved, since that consumer holds the
        evidence.
      properties:
        account_id:
          description: >
            hold the same campaign id in different accounts, so a ref without it
            is not unique.
          title: >
            AccountID is the provider's account/customer identifier. Two
            customers can
          type: string
        external_id:
          title: |
            ExternalID is the provider's own identifier for the object.
          type: string
        kind:
          description: >
            "ad\_group". Free-form: providers keep inventing object types, and
            an allowlist here would need a platform release to track each one.
          title: |
            Kind is what the id names within that provider, e.g. "campaign",
          type: string
        label:
          description: >
            approval card can say "Northline Residences - Wellness Led" rather
            than a number. Never used for matching. The development is fictional
            on purpose: this comment is published verbatim into
            docs-public/api/openapi.json, so a real customer's campaign name
            here names that customer on docs.erdo.ai.
          title: |
            Label is an optional human-readable name, carried so a log line or
          type: string
        provider:
          title: |
            Provider is the integration this ref belongs to, e.g. "google_ads".
          type: string
      title: >
        ExternalRef names one object in an external provider's account that a
        workstream

        governs.
      type: object
    types.AssignmentSummary:
      description: >
        what it is for, where the supervisor thinks it stands, where its RESULT
        stands, and what the latest worker did about it. The two state axes ride
        together because they answer different questions — a completed
        assignment carrying a rejected result is a true row, and one field could
        not say so.
      properties:
        acceptance_criteria:
          type: string
        adoption_state:
          type: string
        assigned_agent_key:
          type: string
        created_at:
          format: date-time
          type: string
        declared_inputs:
          description: >
            was first dispatched, so a reviewer can see what the worker was told
            to work from.
          items:
            $ref: '#/components/schemas/types.AssignmentResourceHandleInput'
          title: >
            DeclaredInputs are the typed references persisted when the
            responsibility
          type: array
        expected_result_kind:
          type: string
        id:
          format: uuid
          type: string
        latest_attempt:
          allOf:
            - $ref: '#/components/schemas/types.AssignmentAttemptSummary'
          description: |
            has attempted yet.
          title: >
            LatestAttempt is the most recent worker's go at it, absent on work
            nothing
        objective:
          type: string
        reason:
          type: string
        slug:
          type: string
        work_state:
          type: string
        work_state_reason:
          type: string
      title: >
        AssignmentSummary is one bounded responsibility as a coordinator reads
        it:
      type: object
    types.DecisionSummary:
      description: >
        returning operator read, the same shape for both on purpose: the agent's
        copy of what the organization committed to cannot be the only one, or a
        human has no way to check what it acts on. So both surfaces render the
        same five facts (decision, rationale, authority, execution,
        supersession) instead of each deriving their own. It is deliberately not
        the whole record: declared effects, per-action inputs and the
        measurement contract are a drill-in, and would push the ledger read past
        what a model can usefully hold.
      properties:
        age_seconds:
          format: int64
          type: integer
        agent_run_id:
          format: uuid
          type: string
        alternatives_considered:
          description: >
            before proposing this — the WHY's companion, so a reader can tell a
            choice from the only idea anyone had. Empty is ordinary: most calls
            had no real alternative, and the record says so rather than
            inventing one.
          title: >
            AlternativesConsidered is the producer's account of what else it
            weighed
          type: string
        applicability:
          description: >
            that outlives the work it authorized, or an authorization for
            exactly the actions it named. It travels with the summary because
            the two are read differently — a standing decision applies until its
            review deadline or explicit retirement, while a one\_shot in the
            current list is work still in flight to see through, not a strategy
            to keep running.
          title: >
            Applicability is standing or one_shot: whether this decision is a
            course
          type: string
        approval_id:
          description: >
            approval producer family. It travels on the row so the join runs in
            both directions from one read: a caller holding an approval filters
            the list by it, and a caller reading a page of decisions can index
            them by the approvals they answer without a call per row.
          format: uuid
          title: >
            ApprovalID is the ask this decision was made on, present only for
            the
          type: string
        authorized_at:
          format: date-time
          type: string
        decided_by_name:
          description: >
            name, else email), so a surface can say "X did Y" without carrying a
            user lookup of its own. Empty when no human decided (an agent or a
            policy did), or when the id could not be resolved in the caller's
            organization — a manager acting into a client org is the case that
            does not resolve, and the raw id stays on DecidedByUserID for that.
            It is display-only and never a filter.
          title: >
            DecidedByName is the human decider resolved to a name (display name,
            else
          type: string
        decided_by_user_id:
          format: uuid
          type: string
        decider_kind:
          description: |
            deterministic\_policy, safe\_default or system.
          title: |
            DeciderKind is who exercised the judgement: human, llm_agent,
          type: string
        decider_rationale:
          description: >
            they supplied any. Usually empty — approving a card records no
            sentence.
          title: >
            DeciderRationale is the deciding human's own words about the answer,
            when
          type: string
        decision_class:
          description: >
            (\`paid\_media.ad\_group.pause\`), provider-agnostic and stable
            across the tools that implement it. Source is the producer family
            that recorded it.
          title: |
            DecisionClass is what KIND of decision this is
          type: string
        evidence_kind:
          description: >
            specified state exists), experimental (a controlled comparison), or
            observational (a before/after movement with no control). Empty when
            the settled effects disagree — a decision with one experimental and
            one deterministic result has no single kind, and picking one would
            attach the stronger claim to both.
          title: |
            EvidenceKind is what KIND of evidence settled it: deterministic (the
          type: string
        execution_status:
          description: >
            change the decision authorized actually reached the outside world.
            pending | started | succeeded | failed | unknown, and empty when the
            decision authorized no action at all.
          title: >
            ExecutionStatus rolls the child actions up into one word: whether
            the
          type: string
        exit_condition:
          type: string
        has_pending_effects:
          description: >
            outcome. An effective decision can legitimately be in this state
            between its action landing and the settlement sweep starting
            measurement, so clients must not infer that an empty outcome means
            the decision is finished.
          title: >
            HasPendingEffects says whether at least one measurable effect still
            owes an
          type: boolean
        lapsed:
          type: boolean
        outcome_label:
          description: >
            says the same thing about the same row rather than each deriving its
            own vocabulary from the pair above. Only an experiment may say a
            change "worked"; deterministic evidence says "confirmed" and
            observational says "moved as expected".


            Empty whenever the pair cannot support one phrase — mixed outcomes,
            mixed evidence kinds — because there is no honest single sentence
            for those and the per-effect labels in the detail read are the
            answer.
          title: >
            OutcomeLabel is the server's own words for this outcome, so every
            surface
          type: string
        outcome_status:
          description: >
            not\_met, inconclusive, or \`mixed\` when they disagree. Empty while
            nothing has settled, which is a different fact from inconclusive —
            one says the answer is not in yet, the other says the evidence could
            not produce one.


            Effects that are unmeasurable, censored, or parked in
            measurement\_unavailable contribute nothing here. They are coverage,
            they are visible as such in the detail read and the scorecard, and
            folding them in would let a decision nobody could measure read as
            one that did not work.
          title: >
            OutcomeStatus rolls this decision's SETTLED effects into one word:
            met,
          type: string
        proposed_at:
          format: date-time
          type: string
        rejected_at:
          description: >
            whose status is \`rejected\`.


            It is nullable when the source has no trustworthy answer fact, and
            is never inferred from a write clock.
          format: date-time
          title: >
            RejectedAt is when the proposal was refused, and it is present only
            on a

            decision
          type: string
        review_by:
          description: >
            never a lifecycle status or a destructive rewrite of the original
            record.
          format: date-time
          title: >
            ReviewBy includes the legacy creation-time fallback. Lapsed is
            derived,
          type: string
        slug:
          type: string
        source:
          type: string
        status:
          type: string
        subject_kind:
          description: |
            names it — a campaign, a page, a lead form.
          title: >
            SubjectKind / SubjectLabel name what the decision is about, as the
            operator
          type: string
        subject_label:
          type: string
        superseded_by_decision_slug:
          description: >
            decision that later replaced this one. It carries the same
            past-authorization rule the currentness read applies — a reversal
            somebody PROPOSED and a human then refused has not replaced
            anything, and showing it here would report a course as retired
            exactly when the human voted to keep it.
          title: >
            SupersededByDecisionSlug is the other direction of the same link:
            the
          type: string
        supersedes_decision_slug:
          description: >
            the producer declared the link explicitly — a reversal states what
            it reverses, and nothing infers it from two decisions sharing a
            subject.
          title: >
            SupersedesDecisionSlug names the decision this one replaced. Set
            only when
          type: string
        what:
          description: >
            PRODUCER's rationale — the argument the proposal was made on. When a
            human gave their own reason for the answer it is in
            DeciderRationale, never merged into this one: reading a proposal's
            argument as the approver's reason for accepting it is how a record
            starts attributing motives.
          title: |
            What is the decision in one line of business English; Why is the
          type: string
        why:
          type: string
        workstream_id:
          description: >
            filed under and the run that proposed it. They travel on the summary
            so a surface rendering one row can link the workstream without a
            second read — the same reason ApprovalID travels. Both are optional
            in fact as well as shape: an org-level decision belongs to no
            workstream, and a deterministic producer may have no run.
          format: uuid
          title: >
            WorkstreamID / AgentRunID are provenance: the workstream the
            decision was
          type: string
      title: >
        DecisionSummary is the compact projection of one decision that both a
        continuing

        agent and a
      type: object
    types.WorkstreamEvent:
      description: >
        — a git-log-style record of what happened and what's next. Body is
        free-form; actor\_type/actor\_id is attribution (identity, not routing).
      properties:
        actor_id:
          format: uuid
          type: string
        actor_type:
          type: string
        body:
          type: string
        created_at:
          format: date-time
          type: string
        id:
          format: uuid
          type: string
        organization_id:
          format: uuid
          type: string
        workstream_id:
          format: uuid
          type: string
      title: >
        WorkstreamEvent is one entry in a workstream's append-only,
        chronological log
      type: object
    types.WorkstreamResource:
      properties:
        created_at:
          format: date-time
          type: string
        id:
          format: uuid
          type: string
        relationship_type:
          type: string
        resource_id:
          format: uuid
          type: string
        resource_type:
          type: string
        title:
          type: string
        workstream_id:
          format: uuid
          type: string
      title: >
        WorkstreamResource is a typed link from a workstream to another domain
        object.
      type: object
    types.Workstream:
      description: >
        Operational state machine for multi-step work (campaign launches,
        reports, monitors).
      properties:
        autonomy_mode:
          description: >
            (autopilot|propose|strict); nil inherits the org-level setting. The
            engine gate resolves effective mode = workstream ?? org ?? propose.
          title: |
            AutonomyMode is this workstream's autonomy override
          type: string
        completed_at:
          format: date-time
          type: string
        created_at:
          format: date-time
          type: string
        description:
          type: string
        escalation_budget_per_day:
          format: int32
          maximum: 2147483647
          minimum: -2147483648
          type: integer
        external_refs:
          description: >
            machine-readable answer to "which campaigns is this managing?".
            Always present (empty when nothing is declared) so a reader never
            has to tell "governs nothing" from "field absent". It rides along on
            every workstream read, including each entry of a root's
            ChildPortfolio, so a portfolio loop gets the whole account's scope
            from the ledger read it already makes.
          items:
            $ref: '#/components/schemas/types.ExternalRef'
          title: >
            ExternalRefs are the provider-owned objects this workstream governs
            — the
          type: array
        id:
          format: uuid
          type: string
        organization_id:
          format: uuid
          type: string
        primary_thread_id:
          format: uuid
          type: string
        project_id:
          format: uuid
          type: string
        revision:
          description: >
            budgets, autonomy and external refs that say what it IS. Spend
            accrual and reconciliation pass counters write the same row without
            moving it, so a coordinator's read is not invalidated by a worker's
            cost landing mid-pass. It rides on every read because it is what a
            writer writes against: if a human steered or a result landed
            meanwhile, the write is refused and the pass re-reads instead of
            deciding about a world that has moved.
          format: int64
          title: >
            Revision counts the authoritative mutations of this workstream: the
            state,

            title, description,
          type: integer
        slug:
          type: string
        source_template_id:
          format: uuid
          type: string
        spent_millicents:
          format: int64
          type: integer
        started_at:
          format: date-time
          type: string
        status:
          type: string
        title:
          type: string
        token_budget_millicents:
          description: >
            ceiling (nil = unlimited); SpentMillicents is the running total
            accrued from completed engine work; EscalationBudgetPerDay caps
            urgent items per rolling 24h (nil = org default). Millicents are
            thousandths of a cent: money.MillicentsPerDollar (100,000) per
            dollar, which is the unit provider.CostBreakdown.Millicents() writes
            spend in.
          format: int64
          title: |
            Budget envelope (work-engine D6). TokenBudgetMillicents is the spend
          type: integer
        updated_at:
          format: date-time
          type: string
      title: |
        Workstream represents a piece of business work in motion.
      type: object
    types.AssignmentResourceHandleInput:
      description: >
        service owns, as a dispatching producer declares it. It mirrors the
        handle the funnel stores, and it is what replaces "the worker can read
        the parent's transcript": an assignment attempted a week after its
        coordinator exited has no transcript to inherit, so every input it works
        from is named here. RevisionRef pins content that can change, so the
        worker and the coordinator who judges its result are looking at the same
        thing.
      properties:
        resource_id:
          type: string
        resource_type:
          type: string
        revision_ref:
          type: string
      title: |
        AssignmentResourceHandleInput is one typed pointer at something a domain
      type: object
    types.AssignmentAttemptSummary:
      description: |
        status, which belongs to the agent service and is not mirrored here.
      properties:
        affected_output:
          type: string
        agent_run_id:
          format: uuid
          type: string
        attempt_number:
          format: int64
          type: integer
        ended_at:
          format: date-time
          type: string
        handles:
          description: >
            the revision the worker produced. This is what a reviewer validates
            and what an acceptance attaches; the summary is only how the worker
            described it.
          items:
            $ref: '#/components/schemas/types.AssignmentResourceHandleInput'
          title: >
            Handles are the domain objects the submission consists of, each
            pinned to
          type: array
        output: {}
        result_kind:
          description: >
            unaltered beside the assignment's expected\_result\_kind rather than
            reconciled with it, so a reviewer can see that the two disagree —
            which is a fact about the submission and often the reason to reject
            it.
          title: >
            ResultKind is what the worker BELIEVES it produced, as declared.
            Carried
          type: string
        state:
          type: string
        summary:
          description: >
            attempt submitted. It is never the result itself: a summary that
            could stand in for the work would let an unverified sentence become
            current state.
          title: >
            Summary is the submitted result's bounded description, present once
            the
          type: string
        terminal_cause:
          type: string
        terminal_reason:
          type: string
      title: >
        AssignmentAttemptSummary is one worker's execution lifecycle — never the
        run's
      type: object
  responses:
    APIError:
      content:
        application/json:
          schema:
            externalDocs:
              url: https://pkg.go.dev/encore.dev/beta/errs#Error
            properties:
              code:
                description: Error code
                example: not_found
                externalDocs:
                  url: https://pkg.go.dev/encore.dev/beta/errs#ErrCode
                type: string
              details:
                description: Error details
                type: object
              message:
                description: Error message
                type: string
            title: APIError
            type: object
      description: Error response
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: An Erdo API key (erdo_api_...) or scoped token (erdo_token_...).

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.