Skip to main content

​
Overview

The /instruct endpoint allows you to send instructions to your Hyperaide assistant programmatically. Your assistant will process the instruction and take appropriate actions, just as if you had messaged it directly.
Use this endpoint when you want your assistant to actively respond and take actions based on your instruction.

​
Endpoint

POST https://api.hyperaide.com/instruct

​
Authentication

Include your API key in the request headers: 
x-api-key: your_api_key_here

​
Request Body

​
content
string
required
The instruction you want to send to your assistant. Can be any natural language instruction.Example: "Create a task to review the Q4 budget by Friday"

​
Request Example

curl -X POST https://api.hyperaide.com/instruct \
  -H "x-api-key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Create a task to review the Q4 budget by Friday"
  }'

​
Response

​
Success Response (200 OK)

{
  "message": "Hyperaide instructed"
}
The instruction has been queued and your assistant will process it asynchronously. Your assistant will execute the instruction and any resulting actions (creating tasks, sending messages, updating databases, etc.) will happen in the background.
The API returns immediately after queuing the instruction. Your assistant processes it asynchronously and will perform actions based on your instruction.

​
Error Responses

Missing or invalid API key
{
  "error": "Invalid API key"
}
Verify your API key is correct and included in the x-api-key header.
Missing or invalid parameters
{
  "error": "Instruction is required"
}
Ensure you’re sending the content field in the request body.
User not found
{
  "error": "User not found"
}
The API key is valid but the associated user doesn’t exist. Contact support.
Server error
{
  "error": "An error occurred queuing your request",
  "message": "Detailed error message"
}
Something went wrong on our end. Try again or contact support if the issue persists.

​
Use Cases

  • Task Creation
  • Workflow Automation
  • Smart Notifications
  • Data Processing
Automatically create tasks from external systems
// When a GitHub issue is created
await fetch('https://api.hyperaide.com/instruct', {
  method: 'POST',
  headers: {
    'x-api-key': process.env.HYPERAIDE_API_KEY,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    content: `Create a task to review GitHub issue #${issue.number}: ${issue.title}`
  })
});

​
Best Practices

Be Specific

Provide clear, detailed instructions just as you would when messaging your assistant directly

Include Context

Add relevant context in your instruction to help your assistant make better decisions

Error Handling

Always check response status codes and implement proper error handling

Rate Limiting

Be mindful of rate limits when making multiple requests. Implement exponential backoff if needed.

​
What Happens Next?

After you send an instruction:
  1. Queued: The instruction is immediately queued for processing
  2. Processed: Your assistant analyzes the instruction and determines appropriate actions
  3. Executed: Actions are performed (creating tasks, sending messages, updating databases, etc.)
  4. Notifications: If configured, you’ll receive notifications about the results through your connected channels
You can check the results of your instruction by messaging your assistant or checking the web app. Your assistant maintains context of API-triggered instructions just like any other interaction.

POST /inform

Use this endpoint if you want to provide information without expecting actions