Skip to main content
◈hastdocs
English
Hast home

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.

Create channels through API or MCP

Use a Profile API key with channels:write; reads require channels:read. Single-Agent conversation keys cannot manage channels. Paths below are relative to $HAST_API_BASE.

OperationREST APIMCP tool
Create or resume setupPOST /channels/automaticpost_channels_automatic
Read progressGET /channels/automatic/{setup_id}get_channels_automatic_setup_id
Obtain consent URLPOST /channels/automatic/{setup_id}/authorizepost_channels_automatic_setup_id_authorize
Register verified channelPOST /channels/automatic/{setup_id}/completepost_channels_automatic_setup_id_complete
Cancel incomplete setupDELETE /channels/automatic/{setup_id}delete_channels_automatic_setup_id

Example create body. Generate a new UUID for each new setup; retries of the same setup preserve its UUID, provider and name:

{"provider":"slack","name":"Customer Support","request_key":"7d4ee264-3665-4d51-9363-b43bb302a790"}

Choose slack or telegram; names allow 35 or 64 characters respectively. The response id is the subsequent setup_id. MCP creation wraps this object in body; subsequent calls put the returned ID in path.setup_id.

  1. Call authorize. Slack requires a temporary configuration_token (Slack Configuration Access Token), supplied from secure client storage, never chat, logs or a repository. Telegram uses {}. MCP authorization takes both path and body.
  2. The authorized owner opens the returned url. Complete Slack consent; at awaiting_verification, open verification_url and click Click here to verify. In Telegram, press START, then Create my bot, and confirm the bot name and username. API/MCP does not replace the owner's provider consent.
  3. Poll the same setup. When status=complete, call complete and retain connection.id. Initial registration returns 201; repeated completion returns the same connection with 200. No Agent is bound automatically.
  4. Read the Agent's existing channels, then save the full desired connection_ids through PUT /webhooks/{hook_id}/channels. Preserve other intended bindings. Verify a controlled incoming message and the actual channel reply.

Incomplete setups expire after 30 minutes. For failed, expired, canceled or uncertain, inspect error_code and existing effects before proceeding; do not blindly create another bot with a new UUID. The deployment fixes callback and return destinations, and the key fixes the Profile. Cancellation clears incomplete setup credentials without deleting an external App/Bot already created. Completed setups use normal channel disconnect/removal.

Run history, email and channel settings

These management routes have matching MCP tools. Use the API reference and refreshed tool schemas for exact parameters.

CapabilityAPI and scope
Agent runsGET /webhooks/{hook_id}/runs with limit and cursor; /runs/{task_id} reads the exact execution. Requires webhooks:read
Tokens and estimated costAgent details and GET /schedules/{scheduleID}/runs return token_usage; require webhooks:read and schedules:read respectively
Email namesUnder /webhooks/{hook_id}, GET /email/address-suggestion, GET /email/address?local_part=NAME, then PUT /email/address with local_part and current address_version. Requires channels:read/write
Multiple connector accountsGET /connectors/accounts; connect another through POST /connectors/{provider}/oauth/authorize. Requires connectors:read/write
Slack progressPATCH /channels/{connection_id}/slack accepts show_tool_progress. Requires channels:write
Telegram rules and streamingPATCH /channels/{connection_id}/telegram accepts default_group_mode, show_tool_progress and streaming_replies. Requires channels:write

Read /channels/{connection_id}/installation before updating settings and preserve complete trigger-rule arrays. Omitted optional flags preserve saved values. New Telegram channels wake on mentions or replies in groups; existing rules are retained. Renamed email addresses remain inbound aliases; reread after version or name conflicts instead of reporting a successful rename.

Runtime execute_tool and proxy_execute select accounts through local connector_account_ref_id, required when multiple accounts for a provider are ready. Account-management APIs are separate from provider business-tool execution.

Execution, delivery and business coverage are separate outcomes. Unknown usage is not zero, estimated cost is not a settled charge, and budget_status=unavailable means no Agent/run budget ledger exists. Pruned history cannot be recovered.

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.