# HeyReagent docs

> HeyReagent lets your own tools do things on your own LinkedIn account: send a message, search for people, read a post. Each thing it can do is an action, and you ask for one action at a time. MCP and API for LinkedIn. Not affiliated with LinkedIn.

## How every call is made

- Where: a POST to `https://api.heyreagent.com/v1/actions/<name>`.
- Who: the header `Authorization: Bearer YOUR_KEY`. A key is made on the thread page, under Menu, then Developers, and is shown once.
- What: the action's inputs as JSON in the body. Send `{}` when it needs none.
- It worked: `{ "ok": true, "result": { … } }`.
- It did not: `{ "ok": false, "error": "…", "message": "…" }`. The message says why, in plain English.
- `GET https://api.heyreagent.com/v1/actions`, with the same header, lists every action the plan includes and its inputs.
- The whole API as an OpenAPI 3.1 file: https://heyreagent.com/openapi.json

## Use it from an AI app (MCP)

The MCP address is `https://api.heyreagent.com/mcp`.

### Claude

Signs in to your account. No key.

1. Open Customize, then Connectors.
2. Click + Add, then Add custom connector.
3. Type a name, paste the address, and click Continue.
4. Keep the sign-in settings Claude found, continue, and click Add. Sign in to HeyReagent when Claude asks.
5. In a chat, press + at the lower left, then Connectors, to switch it on.

### ChatGPT

Signs in to your account. No key.

1. Open Settings, then Security and login, and turn on Developer mode.
2. Go to ChatGPT Plugins, select the plus button, type a name and a description, enter the address, and create the connection.
3. Sign in to HeyReagent when ChatGPT asks.
4. In a chat, choose Developer mode from the plus menu and select it.

### Muse

Uses your key.

1. Send Muse the message below, as it is.
2. Muse answers with a card for the connector. Press Connect on it, then Continue, and paste your key in the form. The key goes there, not in the chat.
3. Muse asks whether it may share information with api.heyreagent.com. “Always allow this site” stops it asking before every request. “Allow once” allows the next one only.
4. Muse lists the actions and runs the check. Then ask it for what you want.

```
Create a custom connector called HeyReagent for my LinkedIn. It is a remote MCP server over streamable HTTP at https://api.heyreagent.com/mcp. Every request needs the header "Authorization: Bearer" followed by my key. Ask me for the key in your secure form, not in this chat. Then list its tools and run get_my_profile to check that it works.
```

### Claude Code

Uses your key.

1. Run this in a terminal, with your own key where it says YOUR_KEY.

```
claude mcp add --transport http heyreagent https://api.heyreagent.com/mcp \
  --header "Authorization: Bearer YOUR_KEY"
```

### Cursor

Uses your key.

1. Put this in .cursor/mcp.json in your project, or in ~/.cursor/mcp.json to have it everywhere, with your own key where it says YOUR_KEY.

```
{
  "mcpServers": {
    "heyreagent": {
      "url": "https://api.heyreagent.com/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_KEY"
      }
    }
  }
}
```

### n8n

Uses your key.

1. Add an MCP Client Tool node to your agent.
2. Endpoint: the address above. Server Transport: HTTP Streamable.
3. Authentication: Bearer Auth, with your key.

## When it says no

| Error | Status | What it means | What to do |
|---|---|---|---|
| `invalid_key` | 401 | The key is missing or wrong. | Send it as the header Authorization: Bearer YOUR_KEY. Create a new key if you lost it. |
| `unknown_action` | 404 | There is no action with that name. | Check the spelling against the list below. |
| `invalid_json` | 400 | The body is not JSON. | Send JSON, such as {} for an action that needs nothing. |
| `invalid_input` | 422 | An input is missing, or is not the kind of value the action takes. | The message names each input and what is wrong with it. The action’s page lists its inputs. |
| `plan_required` | 402 | The account was switched off. | Nothing runs on it until it is switched on again. |
| `upgrade_required` | 402 | The action is part of the Agent plan. | Use a Connect action, or change plan. |
| `linkedin_disconnected` | 409 | On the free plan, LinkedIn is not connected right now. | Run connect_linkedin and open the url it gives. |
| `free_plan_full` | 409 | Every free seat is taken at the moment. | Try again in a little while, or choose a plan. |
| `free_plan_taken` | 409 | This LinkedIn account already has a free plan under another email. | Sign in with that email, or choose a plan for this one. |
| `no_live_account` | 422 | No LinkedIn account is connected. | Run connect_linkedin and open the url it gives. |
| `daily_limit_reached` | 422 | Today’s limit for this kind of action is used up. | Wait until the time in resetAt. |
| `weekly_limit_reached` | 422 | The invitations of the last 7 days are used up. | Wait until the time in resetAt. get_usage shows the count. |
| `note_limit_reached` | 422 | A free LinkedIn account has sent its invitations with a note for 30 days. | Send the invitation without a note, or wait until the time in resetAt. |
| `note_too_long` | 422 | The note is longer than this LinkedIn account can send. | Shorten it to the number in limit, or send the invitation without a note. |
| `linkedin_limit_reached` | 422 | LinkedIn itself refused: its own limit is reached. | Wait. It is usually LinkedIn’s own invitation limit. |
| `reconnect_needed` | 422 | LinkedIn signed the account out. | Run update_linkedin_connection and sign in again. |
| `account_restricted` | 422 | LinkedIn does not let this account do that. | Read the message, and check the account on LinkedIn itself. |
| `not_available_on_this_account` | 422 | The LinkedIn account does not have the product the action needs, such as Sales Navigator or Recruiter. | Use an action for ordinary LinkedIn, or an account that has the product. |
| `not_found` | 422 | Nothing with that id is on your account. | Check where the id came from: each action’s page says where to get it. |
| `temporary_failure` | 422 | LinkedIn did not answer this time. | Try again. The answer says retryable: true. |
| `temporarily_unavailable` | 422 | The action could not be run right now, or you made more than 300 calls in a minute. | Wait a minute and try again. |
| `failed` | 422 | It was refused for another reason. | The message says why. |

A request sent as a GET answers with a web page that says `Cannot GET`: it has to be a POST. An input name the action does not know is left out without a word.

## Limits

Each LinkedIn account has a daily limit per kind of action, to keep the account safe. Reading your conversations is not limited. `get_usage` shows what is used and what is left. An action past a limit is refused with the time it resets.

| What | A day |
|---|---|
| Invitations sent (20 on a free LinkedIn account) | 30 |
| Invitations accepted or declined | 100 |
| Invitations taken back | 100 |
| Messages sent | 100 |
| InMails sent | 40 |
| Messages edited, deleted or reacted to, and conversations deleted | 100 |
| Comments on posts | 40 |
| Reactions to posts | 40 |
| Posts published | 5 |
| Profiles read | 100 |
| Skills endorsed | 20 |
| Leads saved, and Recruiter candidates moved or rejected | 100 |
| Job postings created, edited, published or closed | 20 |
| Search results (rows) | 1,000 |
| Search results on Sales Navigator or Recruiter (rows) | 2,500 |

### Invitations have more limits

Invitations are also limited over a week and, on a free LinkedIn account, in how many can carry a note. How many you can send depends on whether the LinkedIn account is a paid one (Premium, Sales Navigator or Recruiter) or a free one. An account HeyReagent cannot tell apart counts as free.

| Invitations | Paid account | Free account |
|---|---|---|
| In a day | 30 | 20 |
| In any 7 days | 200 | 150 |
| With a note, in any 30 days | no limit of its own | 5 |
| Characters in a note | 300 | 200 |

Past the 7 days' limit an invitation is refused with `weekly_limit_reached`. Past the notes of a free account it is refused with `note_limit_reached`: send it without a note. A note that is too long is refused with `note_too_long`.

### What the limits do not do for you

- Spread your calls over the day. Calls made at the same minute every day can be flagged as automation.
- A LinkedIn account that is new, has few connections, or was not used for a long time should start well below these numbers and go up gradually.
- LinkedIn can refuse sooner than these numbers. The answer is then `linkedin_limit_reached`.

## Plans

Every account starts on the free plan, which has every action marked Free and Connect. On the free plan LinkedIn is disconnected after a while without use; an action then answers `linkedin_disconnected`, and `connect_linkedin` gives the link to connect it again. The Connect plan keeps LinkedIn connected, so scheduled workflows run. The actions marked Agent need the Agent plan. Sales Navigator, Recruiter and job-posting actions run on your own LinkedIn account and need that product on it.

## Actions

### Profile

- [get_my_profile](https://heyreagent.com/md/docs/actions/get_my_profile.md): Get my profile
- [get_profile](https://heyreagent.com/md/docs/actions/get_profile.md): Get a profile
- [update_my_profile](https://heyreagent.com/md/docs/actions/update_my_profile.md): Update my profile
- [get_profile_details](https://heyreagent.com/md/docs/actions/get_profile_details.md): Get a profile in depth
- [endorse_skill](https://heyreagent.com/md/docs/actions/endorse_skill.md): Endorse a skill

### Network

- [list_connections](https://heyreagent.com/md/docs/actions/list_connections.md): List my connections
- [send_invitation](https://heyreagent.com/md/docs/actions/send_invitation.md): Send an invitation
- [list_sent_invitations](https://heyreagent.com/md/docs/actions/list_sent_invitations.md): List sent invitations
- [preview_withdraw_invitations](https://heyreagent.com/md/docs/actions/preview_withdraw_invitations.md): Preview withdrawing invitations
- [withdraw_invitations](https://heyreagent.com/md/docs/actions/withdraw_invitations.md): Withdraw sent invitations
- [withdraw_invitation](https://heyreagent.com/md/docs/actions/withdraw_invitation.md): Withdraw one sent invitation, now
- [list_received_invitations](https://heyreagent.com/md/docs/actions/list_received_invitations.md): List received invitations
- [respond_to_invitation](https://heyreagent.com/md/docs/actions/respond_to_invitation.md): Accept or decline an invitation
- [list_followers](https://heyreagent.com/md/docs/actions/list_followers.md): List followers

### Messages

- [list_conversations](https://heyreagent.com/md/docs/actions/list_conversations.md): List conversations
- [get_conversation](https://heyreagent.com/md/docs/actions/get_conversation.md): Get a conversation
- [send_message](https://heyreagent.com/md/docs/actions/send_message.md): Send a message
- [mark_read](https://heyreagent.com/md/docs/actions/mark_read.md): Mark a conversation read in this inbox
- [sync_inbox](https://heyreagent.com/md/docs/actions/sync_inbox.md): Refresh the inbox
- [get_send_status](https://heyreagent.com/md/docs/actions/get_send_status.md): Check how an inbox refresh ended
- [list_chats](https://heyreagent.com/md/docs/actions/list_chats.md): List chats
- [get_chat](https://heyreagent.com/md/docs/actions/get_chat.md): Get a chat
- [list_chat_messages](https://heyreagent.com/md/docs/actions/list_chat_messages.md): List a chat's messages
- [list_chat_participants](https://heyreagent.com/md/docs/actions/list_chat_participants.md): List who is in a chat
- [send_chat_message](https://heyreagent.com/md/docs/actions/send_chat_message.md): Send a message with files or a voice note
- [start_conversation](https://heyreagent.com/md/docs/actions/start_conversation.md): Start a conversation (InMail, group, company)
- [set_chat_status](https://heyreagent.com/md/docs/actions/set_chat_status.md): Mark a chat read or muted on LinkedIn
- [resync_chat](https://heyreagent.com/md/docs/actions/resync_chat.md): Re-read a chat's history
- [delete_chat](https://heyreagent.com/md/docs/actions/delete_chat.md): Delete a chat
- [list_messages](https://heyreagent.com/md/docs/actions/list_messages.md): List messages across chats
- [get_message](https://heyreagent.com/md/docs/actions/get_message.md): Get a message
- [get_message_attachment](https://heyreagent.com/md/docs/actions/get_message_attachment.md): Download a message attachment
- [edit_message](https://heyreagent.com/md/docs/actions/edit_message.md): Edit a sent message
- [delete_message](https://heyreagent.com/md/docs/actions/delete_message.md): Delete a sent message
- [react_to_message](https://heyreagent.com/md/docs/actions/react_to_message.md): React to a message
- [list_chat_attendees](https://heyreagent.com/md/docs/actions/list_chat_attendees.md): List everyone I have chats with
- [get_chat_attendee](https://heyreagent.com/md/docs/actions/get_chat_attendee.md): Get a chat participant
- [get_chat_attendee_picture](https://heyreagent.com/md/docs/actions/get_chat_attendee_picture.md): Download a participant's picture
- [list_attendee_chats](https://heyreagent.com/md/docs/actions/list_attendee_chats.md): List my chats with one person
- [list_attendee_messages](https://heyreagent.com/md/docs/actions/list_attendee_messages.md): List my messages with one person
- [resync_attendee_chats](https://heyreagent.com/md/docs/actions/resync_attendee_chats.md): Re-read my chats with one person

### InMail

- [list_inmail](https://heyreagent.com/md/docs/actions/list_inmail.md): List InMail conversations
- [get_inmail_conversation](https://heyreagent.com/md/docs/actions/get_inmail_conversation.md): Get an InMail conversation
- [get_inmail_credits](https://heyreagent.com/md/docs/actions/get_inmail_credits.md): Get InMail credits
- [list_sales_navigator_contracts](https://heyreagent.com/md/docs/actions/list_sales_navigator_contracts.md): List Sales Navigator contracts
- [switch_sales_navigator_contract](https://heyreagent.com/md/docs/actions/switch_sales_navigator_contract.md): Switch Sales Navigator contract

### Search

- [search_people](https://heyreagent.com/md/docs/actions/search_people.md): Search people
- [search_posts](https://heyreagent.com/md/docs/actions/search_posts.md): Search posts
- [search_linkedin](https://heyreagent.com/md/docs/actions/search_linkedin.md): Search LinkedIn with any filter
- [lookup_search_ids](https://heyreagent.com/md/docs/actions/lookup_search_ids.md): Look up the id for a search filter
- [search_linkedin_people](https://heyreagent.com/md/docs/actions/search_linkedin_people.md): Search people, every filter typed
- [search_linkedin_companies](https://heyreagent.com/md/docs/actions/search_linkedin_companies.md): Search companies, every filter typed
- [search_linkedin_posts](https://heyreagent.com/md/docs/actions/search_linkedin_posts.md): Search posts, every filter typed
- [search_linkedin_jobs](https://heyreagent.com/md/docs/actions/search_linkedin_jobs.md): Search jobs, every filter typed
- [search_linkedin_sales_navigator_people](https://heyreagent.com/md/docs/actions/search_linkedin_sales_navigator_people.md): Search people in my Sales Navigator, every filter typed
- [search_linkedin_sales_navigator_companies](https://heyreagent.com/md/docs/actions/search_linkedin_sales_navigator_companies.md): Search companies in my Sales Navigator, every filter typed
- [search_linkedin_recruiter_people](https://heyreagent.com/md/docs/actions/search_linkedin_recruiter_people.md): Search candidates in my Recruiter, every filter typed
- [get_company](https://heyreagent.com/md/docs/actions/get_company.md): Get a company page
- [search_people_sales_navigator](https://heyreagent.com/md/docs/actions/search_people_sales_navigator.md): Search people (Sales Navigator) (Agent plan)
- [count_people_sales_navigator](https://heyreagent.com/md/docs/actions/count_people_sales_navigator.md): Count people (Sales Navigator) (Agent plan)
- [search_companies](https://heyreagent.com/md/docs/actions/search_companies.md): Search companies (Agent plan)
- [find_decision_makers](https://heyreagent.com/md/docs/actions/find_decision_makers.md): Find decision-makers at a company (Agent plan)
- [list_funding_signals](https://heyreagent.com/md/docs/actions/list_funding_signals.md): List recently funded companies (Agent plan)

### Posts

- [get_recent_posts](https://heyreagent.com/md/docs/actions/get_recent_posts.md): Get someone's recent posts
- [get_post_engagers](https://heyreagent.com/md/docs/actions/get_post_engagers.md): Get who engaged with a post
- [create_post](https://heyreagent.com/md/docs/actions/create_post.md): Publish a post
- [comment_on_post](https://heyreagent.com/md/docs/actions/comment_on_post.md): Comment on a post
- [react_to_post](https://heyreagent.com/md/docs/actions/react_to_post.md): React to a post
- [get_post](https://heyreagent.com/md/docs/actions/get_post.md): Get a post
- [list_post_comments](https://heyreagent.com/md/docs/actions/list_post_comments.md): List a post's comments
- [list_post_reactions](https://heyreagent.com/md/docs/actions/list_post_reactions.md): List a post's reactions
- [list_posts_by_author](https://heyreagent.com/md/docs/actions/list_posts_by_author.md): List a person's or company's posts
- [list_comments_by_person](https://heyreagent.com/md/docs/actions/list_comments_by_person.md): List the comments a person wrote
- [list_reactions_by_person](https://heyreagent.com/md/docs/actions/list_reactions_by_person.md): List what a person reacted to

### Sales Navigator

- [save_lead](https://heyreagent.com/md/docs/actions/save_lead.md): Save a Sales Navigator lead

### Recruiter

- [list_hiring_projects](https://heyreagent.com/md/docs/actions/list_hiring_projects.md): List Recruiter hiring projects
- [get_hiring_project](https://heyreagent.com/md/docs/actions/get_hiring_project.md): Get a Recruiter hiring project
- [move_recruiter_candidate](https://heyreagent.com/md/docs/actions/move_recruiter_candidate.md): Add or move a Recruiter candidate
- [reject_recruiter_applicant](https://heyreagent.com/md/docs/actions/reject_recruiter_applicant.md): Reject a Recruiter applicant

### Jobs

- [list_job_postings](https://heyreagent.com/md/docs/actions/list_job_postings.md): List my job postings
- [get_job_posting](https://heyreagent.com/md/docs/actions/get_job_posting.md): Get a job posting
- [list_job_applicants](https://heyreagent.com/md/docs/actions/list_job_applicants.md): List a job posting's applicants
- [get_job_applicant](https://heyreagent.com/md/docs/actions/get_job_applicant.md): Get an applicant
- [get_job_applicant_resume](https://heyreagent.com/md/docs/actions/get_job_applicant_resume.md): Download an applicant's resume
- [create_job_posting](https://heyreagent.com/md/docs/actions/create_job_posting.md): Create a job posting draft
- [edit_job_posting](https://heyreagent.com/md/docs/actions/edit_job_posting.md): Edit a job posting
- [publish_job_posting](https://heyreagent.com/md/docs/actions/publish_job_posting.md): Publish a job posting
- [solve_job_posting_checkpoint](https://heyreagent.com/md/docs/actions/solve_job_posting_checkpoint.md): Finish a job posting verification
- [close_job_posting](https://heyreagent.com/md/docs/actions/close_job_posting.md): Close a job posting

### Insight

- [who_is_waiting_on_me](https://heyreagent.com/md/docs/actions/who_is_waiting_on_me.md): Who is waiting on my reply
- [who_went_cold](https://heyreagent.com/md/docs/actions/who_went_cold.md): Who went cold
- [connections_never_messaged](https://heyreagent.com/md/docs/actions/connections_never_messaged.md): Connections I never messaged
- [engagers_not_connected](https://heyreagent.com/md/docs/actions/engagers_not_connected.md): Engagers I am not connected to

### Account

- [connect_linkedin](https://heyreagent.com/md/docs/actions/connect_linkedin.md): Connect a LinkedIn account
- [update_linkedin_connection](https://heyreagent.com/md/docs/actions/update_linkedin_connection.md): Fix or update a LinkedIn connection
- [list_linkedin_accounts](https://heyreagent.com/md/docs/actions/list_linkedin_accounts.md): List connected LinkedIn accounts
- [get_usage](https://heyreagent.com/md/docs/actions/get_usage.md): Get today's usage and limits
