Skip to content
Skip to main content
API quickstart

AIP

API quickstart

Create an AIP key, call a saved Agent, read replies, and access authorized business resources.

Call a saved AIP Agent from your server and read its conversation results. Manage API keys in the AIP workbench; REST and MCP share the same keys and permissions. See the API reference for endpoint details.

Prepare the URL and key

  1. Select the target Profile (business identity) in AIP. Create and test an Agent, save its configuration, and enable it.
  2. Open Manage API keys, create a key, choose the single-Agent conversation access range, and select the Agent to call.
  3. Enable send messages (agent:invoke). This includes read conversations (agent:conversations:read), which grants access to all of that Agent's historical conversations, including those created by other integrations.
  4. Copy the full key immediately after creation. It will not be shown again.

Set these variables in your server terminal. This is the production URL; use the corresponding backend URL for development or self-hosted deployments:

export HAST_API_BASE='https://backend.hast.so/api/public/v1'
export HAST_API_KEY='<YOUR_SINGLE_AGENT_KEY>'

Submit your first task

curl --fail-with-body --request POST \
  --url "$HAST_API_BASE/agent/prompts" \
  --header "Authorization: Bearer $HAST_API_KEY" \
  --header 'Content-Type: application/json' \
  --data '{"request_id":"message-001","prompt":"Describe your role and the work you can help me complete."}'

The request uses the Agent bound to the key and its saved configuration. Omit session_id to create a conversation; include the returned session_id to continue it. Use a new request_id for each new message, and keep the identifier and request content unchanged when retrying that message.

HTTP 202 means the request was accepted. Save the returned session_id and request_id, then read events to determine the outcome of this run.

Read execution progress

export SESSION_ID='<SESSION_ID_FROM_RESPONSE>'
curl --fail-with-body \
  "$HAST_API_BASE/agent/sessions/$SESSION_ID/events?after=0&limit=100" \
  --header "Authorization: Bearer $HAST_API_KEY"

The response contains events, next_after, and has_more. Pass next_after as after on the next request. Keep paging while has_more is true, even if a page contains no visible events. When no new events are available, wait before polling again.

This endpoint returns user messages, Agent replies, and run status. Wait for run.completed, run.failed, or run.interrupted whose run_id matches the receipt's request_id. A message.completed event only completes one message. See conversation events and SSE for details.

Single-Agent conversations use JSON polling and have no SSE route. Use GET /agent/sessions to find the Agent's historical conversations and read their events.

Use a Profile API key

To access resources belonging to the current business identity, create a Profile API key in Manage API keys and grant the required permissions:

PurposePermission and endpoint
Read saved Agent configurationswebhooks:read, GET /webhooks
Invoke a specific Agentwebhooks:write, POST /webhooks/{hook_id}/invoke
Manage knowledge bases, channels, CRM, or schedulesCorresponding resource permissions; see the API reference
Submit an ordinary task and read eventsprompts:write and sessions:read, POST /prompts and /sessions/{id}/events

Write permissions include the corresponding read permission. A Profile key's /prompts endpoint creates ordinary task sessions without automatically applying a saved AIP Agent configuration. To call a configured Agent, use /webhooks/{hook_id}/invoke or the single-Agent flow above.

Ordinary tasks support SSE at /sessions/{id}/events/stream; see SSE integration. Profile keys and single-Agent keys have different endpoint access: /agent/* and ordinary task paths are not interchangeable.

Continue integration

See the API reference for parameters, responses, and OpenAPI JSON. For external Agent clients, use MCP integration. To call the full Hook URL from an Agent's details page, use Webhook HTTP integration.

Meet HastLearn about Hast AIP, Hast Agent, Hast GTM, and delivery with the FDE team.About AIPConfigure Agents and connect business systems using the FDE delivery workbench.Create your first AgentConfigure, save, and debug an Agent without external services.Configure and manage AgentsSet responsibilities, models, and capabilities, and maintain the active configuration.Manage SkillsWrite, import, and select the skill files used by Agents.Add a knowledge baseOrganize URL, file, and Drive sources; manage knowledge-base membership, indexing, and compiled material.Manage business secretsStore credentials and bind them to Agents without exposing real values in examples.Connect business toolsLet Agents call HTTP services with explicit inputs and authentication.Configure long-term memoryChoose what memory an Agent can read and where new memory is written.Debug an AgentTest saved configurations, conversation continuity, and tool results.Import, export, and copyReuse configurations and recheck resources and credentials after migration.Webhook HTTP integrationInvoke an Agent from your server, continue conversations, read replies, and stop execution.MCP integrationConnect external Agent clients to AIP tools with a Public API Key.Connect SlackBring your Agent into Slack to ask questions, work with files, and collaborate with your team in channels or direct messages.Connect WhatsAppLet customers ask questions, share files, and get replies from your Agent in WhatsApp.Connect WeChat Customer ServiceConnect your Agent to WeChat Customer Service to answer customers in WeChat.API quickstartCreate an AIP key, call a saved Agent, read replies, and access authorized business resources.Conversation events and SSEPoll single-Agent conversation events or stream ordinary task events with a Profile API key.API referenceExplore AIP public API authentication, Agent conversations, and business resource endpoints.About Task AgentPlan, execute, and deliver complete tasks with tools, files, and lasting context.Complete your first taskSubmit a request, check progress, and inspect the final output.Execute tasks and manage conversationsAdd instructions, stop execution, and manage conversation history.Upload, view, and download filesProvide inputs and keep the files created by your tasks.Connect apps and configure capabilitiesAuthorize external apps and maintain context across tasks.Create scheduled tasksSet recurrence and timezone, then inspect each run's result.Task Agent troubleshootingCheck access, connections, task state, and files.About GTMUse a shared website project for research, visibility analysis, and marketing drafts.Create your first GTM projectEnter a website, wait for initialization, and inspect the first results.Manage projects and website contextSwitch projects, refresh site information, and manage project settings.Company analysis and project documentsReview product, competitor, and marketing context before content tasks.SEO and website performanceRead PageSpeed reports for mobile and desktop.AI brand mentionsInspect buyer questions and whether model answers mention your brand.Connect Google AnalyticsAuthorize an account, choose a GA property, and inspect traffic reports.Generate and publish X draftsCreate posts, review previews, and finish publishing on X.Generate article draftsSet style, language, and audience, then review and copy Markdown.Use Growth AgentRead project context or start supported background operations in conversation.Run status and troubleshootingCheck queueing, dependencies, and results without treating unfinished work as missing data.Plans and usageCheck access, consumption, and billing for the current Profile.