HumanFirst MCP

Package and Pipeline API#

The HumanFirst REST API lets you programmatically retrieve and search packages (prompts) in a workspace, and trigger pipeline runs against them. These endpoints are the building blocks for integrating HumanFirst packages into external tools, CI workflows, and agent pipelines.

Overview#

Authentication
List Packages
Search Packages
Get Package
Trigger Ephemeral Pipeline

Authentication#

All API requests require a Bearer token. Pass your API key in the Authorization header:

Authorization: Bearer <your_api_key>

See HumanFirst MCP for instructions on generating an API key.

List Packages#

Retrieve all packages defined in a workspace.

GET /v1alpha1/workspaces/{namespace}/{playbook_id}/prompts

Path parameters

Parameter	Type	Description
`namespace`	string	Your organisation namespace.
`playbook_id`	string	The workspace ID (e.g. `playbook-WC123ABCJ5EFXGGF37UZV3C6`).

Response

Returns a list of package objects. Each object includes:

Field	Type	Description
`id`	string	Unique package identifier.
`name`	string	Human-readable package name.
`contents`	string	The package template body as a Go Template string.
`parameters`	array	Named parameters the template can reference.
`run_mode`	string	`RUN_ONCE` (run once over the whole dataset) or `RUN_EACH_ITEM` (run once per input).
`post_processing`	string	How generated output is split into inputs (e.g. `POSTPROCESSING_NEWLINES`).
`created_at`	timestamp	When the package was created.
`updated_at`	timestamp	When the package was last modified.

Example request

curl -X GET \
  "https://api.humanfirst.ai/v1alpha1/workspaces/my-org/playbook-WC123ABC/prompts" \
  -H "Authorization: Bearer $HF_API_KEY"

Example response

{
  "prompts": [
    {
      "id": "prompt-abc123",
      "name": "Summarise conversation",
      "contents": "Summarise the following conversation in one sentence:\n\n{{ text }}",
      "run_mode": "RUN_EACH_ITEM",
      "post_processing": "POSTPROCESSING_NONE",
      "parameters": [],
      "created_at": "2025-11-01T10:00:00Z",
      "updated_at": "2025-12-15T14:32:00Z"
    }
  ]
}

When to use
To discover which packages are available before fetching or running one — equivalent to humanfirst_package_list in the MCP.

Search Packages#

Search packages by name or content using full-text search.

GET /v1alpha1/workspaces/{namespace}/{playbook_id}/prompts:search

Path parameters

Parameter	Type	Description
`namespace`	string	Your organisation namespace.
`playbook_id`	string	The workspace ID.

Query parameters

Parameter	Type	Description
`predicate`	string	The search query string.

Response

Returns a list of matching package IDs in order of relevance — not full package objects. Use Get Package to retrieve content for a specific result.

Field	Type	Description
`prompt_ids`	string[]	IDs of matching packages, ranked by relevance.

Example request

curl -X GET \
  "https://api.humanfirst.ai/v1alpha1/workspaces/my-org/playbook-WC123ABC/prompts:search?predicate=summarise" \
  -H "Authorization: Bearer $HF_API_KEY"

Example response

{
  "prompt_ids": [
    "prompt-abc123",
    "prompt-def456"
  ]
}

When to use
When you know what a package does but not its exact ID, or when building a package picker that lets a user type a description and find the closest match.

Notes
Results are IDs only. Fetch each result with Get Package to read its content.

Get Package#

Retrieve the full content and configuration of a single package.

GET /v1alpha1/workspaces/{namespace}/{playbook_id}/prompts/{prompt_id}

Path parameters

Parameter	Type	Description
`namespace`	string	Your organisation namespace.
`playbook_id`	string	The workspace ID.
`prompt_id`	string	The package ID returned by List or Search.

Response

Returns a single package object with the same fields as described in List Packages, plus:

Field	Type	Description
`nlg_model_parameters`	object	LLM model settings (model name, temperature, etc.) used when running the package.
`nlg_timeout`	duration	Maximum time allowed for the LLM to generate a response.
`post_processing_delimiter`	string	Delimiter used when `post_processing` is `POSTPROCESSING_DELIMITER`.
`parent_id`	string	ID of the parent package if this package is nested in a folder.
`metadata`	object	Key-value pairs for custom metadata attached to this package.

Example request

curl -X GET \
  "https://api.humanfirst.ai/v1alpha1/workspaces/my-org/playbook-WC123ABC/prompts/prompt-abc123" \
  -H "Authorization: Bearer $HF_API_KEY"

Example response

{
  "prompt": {
    "id": "prompt-abc123",
    "name": "Summarise conversation",
    "contents": "Summarise the following conversation in one sentence:\n\n{{ text }}",
    "run_mode": "RUN_EACH_ITEM",
    "post_processing": "POSTPROCESSING_NONE",
    "parameters": [],
    "nlg_model_parameters": {
      "model": "gpt-4o",
      "temperature": 0.2
    },
    "nlg_timeout": "30s",
    "created_at": "2025-11-01T10:00:00Z",
    "updated_at": "2025-12-15T14:32:00Z"
  }
}

When to use
To inspect the template text before running it, audit model settings, or retrieve a package by ID after a search.

Notes
The contents field is a Go Template string. Variables like {{ text }} are filled in at execution time from the data query or input provided.

Trigger Ephemeral Pipeline#

Run a package against a data query without needing a pre-configured pipeline. The pipeline exists only for the duration of the run.

POST /v1alpha1/playbooks/{namespace}/{playbook_id}/ephemeral-pipeline:trigger

Path parameters

Parameter	Type	Description
`namespace`	string	Your organisation namespace.
`playbook_id`	string	The workspace ID.

Request body

Field	Type	Required	Description
`program`	object	Yes	Specifies the package to run (see below).
`data_query`	object	No	The input data to run the package against. If omitted, the package runs once with no input.
`data_query_parameter_name`	string	No	If set, the data query populates a named package parameter instead of the default `{{ text }}` variable.

program object

{
  "prompt_transform": {
    "prompt_id": "prompt-abc123"
  }
}

data_query object

The data query selects the inputs to process. Each query targets a data source. Accepted query types include conversation inputs, stash items, and simple text queries.

{
  "queries": [
    {
      "query": {
        "@type": "type.googleapis.com/zia.ai.playbook.SimpleQueryRequest",
        "...": "..."
      }
    }
  ],
  "max_processed_items": 100
}

Response

Field	Type	Description
`trigger_id`	string	ID of the triggered pipeline run, used to poll for status.
`generation_run_id`	number	The generation run ID associated with this execution.

Example request

curl -X POST \
  "https://api.humanfirst.ai/v1alpha1/playbooks/my-org/playbook-WC123ABC/ephemeral-pipeline:trigger" \
  -H "Authorization: Bearer $HF_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "program": {
      "prompt_transform": {
        "prompt_id": "prompt-abc123"
      }
    }
  }'

Example response

{
  "trigger_id": "trigger-xyz789",
  "generation_run_id": 42
}

When to use
When you want to run a package on demand without setting up a saved pipeline — for example, in a script that fetches a package, inspects its contents, and immediately runs it against a specific dataset.

Notes

Use the trigger_id to check job status via the Triggers API.
If you have a reusable pipeline already configured in the workspace, use the saved pipeline trigger endpoint instead: POST /v1alpha1/playbooks/{namespace}/{playbook_id}/pipelines/{pipeline_id}:trigger