HCC Docs

Flows

List the environment's flows (active versions)

GET /v1/flows flows:read

Responses

  • 200

    Flows

    Fields
    • data Flow[] required
      Fields
      • name string required
      • version string required

        A hash of the flow definition, or the deploy id

      • environment "live" | "test" required
      • definition object required
      • createdAt string required
      • activatedAt string required

        Since when new calls run this version

      • lastSeenAt string required

        Last time a server reported this version

  • 400

    Invalid request

  • 401

    Missing or invalid API key

  • 404

    Not found

  • 429

    rate_limited, or another limit named by error.code

Register call flow versions

PUT /v1/flows flows:write

hcc.serve calls this on startup (mode: "report") and hcc.flows.deploy from CI (mode: "deploy"). The API key picks the environment (hcc_live_ or hcc_test_). Returns the environment flow endpoint, creating its signing secret on first use. With a live key, alsoTest: true registers the same versions in test too. Every bound agent must be yours (422 unknown_agent) and every bound tool declared. When a version becomes active, its bound tools are synced to agents whose platform keeps tools on the agent.

Body

  • flows object[] required
    Fields
    • name string required
    • version string required
    • timeoutMs integer

      100 to 5000.

    • inputSchema object
    • stateSchema object
    • handlers "call.answered" | "call.no_answer" | "call.voicemail" | "call.hangup" | "call.gather" | "call.agent.tool" | "call.agent.ended" | "call.agent.summary" | "call.custom" | "call.transfer.failed" | "call.error"[]

      Default [].

    • customEvents string[]

      Default [].

    • fallbacks object

      Default {}.

      Fields
      • call.answered object[]
      • call.no_answer object[]
      • call.voicemail object[]
      • call.hangup object[]
      • call.gather object[]
      • call.agent.tool object[]
      • call.agent.ended object[]
      • call.agent.summary object[]
      • call.custom object[]
      • call.transfer.failed object[]
      • call.error object[]
    • tools object[]

      Default [].

      Fields
      • name string required
      • description string
      • parameters object required
      • timeoutMs integer

        100 to 5000.

      • afterSpeech boolean
    • agents object[]

      Default [].

      Fields
      • alias string required
      • agentId string required
      • provider string
      • tools string[]

        Default [].

      • testBranch true
  • mode "report" | "deploy"

    Default "report".

  • endpointUrl string

    Your hcc.serve URL

  • alsoTest boolean

    Live keys only: also register the same versions in test, with the same endpoint URL, so the simulator can run them. The test copy syncs no tools to agent platforms: test calls play the agent in the simulator. Default false.

  • toolSync "all" | "test_branches"

    Test keys only: test_branches syncs tools to test branches and leaves an agent's main alone, which is what hcc dev sends on every save. Default "all".

Responses

  • 200

    Registered versions and the flow endpoint

    Fields
    • data Flow[] required
      Fields
      • name string required
      • version string required

        A hash of the flow definition, or the deploy id

      • environment "live" | "test" required
      • definition object required
      • createdAt string required
      • activatedAt string required

        Since when new calls run this version

      • lastSeenAt string required

        Last time a server reported this version

    • endpoint FlowEndpoint required
      Fields
      • environment "live" | "test" required
      • url string | null required

        Where flow events are POSTed; null until set

      • secret string required

        Signing secret: hcc.serve verifies Hcc-Signature with it

    • warnings FlowBindingWarning[] required

      Agent binding problems that do not block the deploy, e.g. a disabled agent, or an agent bound in both environments on a platform that keeps one tool set per agent

      Fields
      • code "agent_not_routable" | "tools_not_supported" | "agent_bound_in_other_environment" | "test_branch_not_supported" | "native_transfer_in_test_branch" required
      • flow string required
      • alias string required
      • agentId string required

        Our agt_… id

      • message string required
    • test object

      With alsoTest: the versions registered in test, and its endpoint

      Fields
      • data Flow[] required
      • endpoint FlowEndpoint required
  • 400

    Invalid request

  • 401

    Missing or invalid API key

  • 404

    Not found

  • 429

    rate_limited, or another limit named by error.code

Report what a server serves, and read how it differs from what is deployed

POST /v1/flows/observe flows:read

A server built with handler() sends this once on a cold start. It activates nothing. The report is stored on the flow endpoint and the Flows page shows the same differences.

Body

  • flows object[] required
    Fields
    • name string required
    • version string required
    • agents object[] required
      Fields
      • alias string required
      • agentId string required

Responses

  • 200

    How the server differs

    Fields
    • drift FlowDrift[] required
      Fields
      • kind "not_deployed" | "version_differs" | "binding_differs" | "not_served" required
      • flow string required
      • message string required
  • 400

    Invalid request

  • 401

    Missing or invalid API key

  • 404

    Not found

  • 429

    rate_limited, or another limit named by error.code

List the flow versions still in use

GET /v1/flows/in-use flows:read

hcc deploy --live removes frozen versions that are not in this list. With a live key, alsoTest=true includes the test environment.

Query

  • alsoTest "true" | "false"

    Live keys only: test as well

Responses

  • 200

    Versions in use

    Fields
    • data FlowVersionInUse[] required
      Fields
      • flow string required
      • version string required
      • environment "live" | "test" required
      • reason "active" | "live_call" required

        active: new calls run it. live_call: a call still going started on it or last ran it

  • 400

    Invalid request

  • 401

    Missing or invalid API key

  • 404

    Not found

  • 429

    rate_limited, or another limit named by error.code

Get the environment's flow endpoint and signing secret

GET /v1/flow-endpoint flows:read

Responses

  • 200

    Flow endpoint

    Fields
    • data FlowEndpoint required
      Fields
      • environment "live" | "test" required
      • url string | null required

        Where flow events are POSTed; null until set

      • secret string required

        Signing secret: hcc.serve verifies Hcc-Signature with it

  • 400

    Invalid request

  • 401

    Missing or invalid API key

  • 404

    Not found

  • 429

    rate_limited, or another limit named by error.code

Set the environment's flow endpoint URL

PUT /v1/flow-endpoint flows:write

Body

  • url string | null required

    Your hcc.serve URL

Responses

  • 200

    Flow endpoint

    Fields
    • data FlowEndpoint required
      Fields
      • environment "live" | "test" required
      • url string | null required

        Where flow events are POSTed; null until set

      • secret string required

        Signing secret: hcc.serve verifies Hcc-Signature with it

  • 400

    Invalid request

  • 401

    Missing or invalid API key

  • 404

    Not found

  • 429

    rate_limited, or another limit named by error.code