AI Ark

01

Setup

1. 01Create an API key. In AI Ark open Settings → API Management (app.ai-ark.com) and create a key.
2. 02Connect AI Ark. In the superagnt app open Integrations, pick AI Ark, paste the key and press Connect.

02

Credits and limits

Searches, previews, exports and finders spend credits from your own AI Ark account, never your superagnt_ balance. connection_ai_ark_credits_read (action get) shows what is left.

Job statistics, results and submission lists, webhook resends, lists and the balance check are free.

• AI Ark allows 5 requests per second per key by default. Past that, the call fails with RATE_LIMITED (HTTP 429): back off, then retry.
• Finding emails and exporting people run as jobs. Each takes up to 500 submissions in flight per key; past that a submission gets a 400 too many pending requests.
• A job charged but never delivered is refunded automatically within 10 hours, and its trackId then answers 403: submit it again. The submissions action shows refund status.

03

Things to know

Searching

• page (from 0) and size (at most 100) are required on people search, preview and company search.
• One search returns at most 10,000 results. To go further, save the ids you have in a list with connection_ai_ark_lists_write (free) and exclude it through the search's lists filter. Lists hold 10,000 ids and expire after 24 hours.
• Text filters take a mode: SMART (the default, also matches related concepts), WORD (the phrase, other words around it allowed) or STRICT (exact). any matches one value or more, all every value; both take include and exclude, at most 300 values each. A search cannot be exclude filters only.
• Job titles are filtered under contact.experience, by latest, current or previous role.
• A search with no matches can answer 404 Data not found instead of an empty content list. Treat both as no results.
• connection_ai_ark_companies, connection_ai_ark_people and connection_ai_ark_people_export list the industries (148 values) and department and function (592 values) filters without their allowed values. Their lookup action returns them: pass lookup_field (a path the tool's description names, such as account.industries.any.include.content[]), optionally lookup_query and lookup_limit (default 100, at most 500). superagnt_ answers lookup itself: no AI Ark call, no credits, no approval.

From a search to emails

• A people search returns profiles without emails or phone numbers, plus a trackId. Pass it to connection_ai_ark_emails_find within 6 hours: a trackId works once, and a used or expired one answers 404.
• A preview shows masked last names and no trackId, but its person ids work with connection_ai_ark_people_export action person.
• Both job submissions require a webhook HTTPS URL, which AI Ark POSTs to when the job completes. Point it at a superagnt_ inbound webhook endpoint to wake an agent, or at any HTTPS URL you control and poll instead.
• To poll, call the statistics action of connection_ai_ark_email_finder_jobs_read or connection_ai_ark_export_jobs_read until state is DONE, then page through results. Export results answer 409 until then; email-finder results can be read while the job runs.

04

Permissions

Each operation starts with a default level. A deployed agent pauses for a person's approval before an Ask or Always ask operation and runs an Act operation straight away. A person can change any level per tool, for one agent or for the whole workspace: see Permissions.

• Always ask: nothing by default.
• Ask: finding emails, exporting people, finding a mobile number, the personality analysis, and resending a job's webhook.
• Act: every other operation. Searches, previews and reverse lookups spend credits yet run without asking: set them to Ask if an agent should check first.

External MCP clients use their own approval settings, and see every tool that spends AI Ark credits as not read-only.

05

Examples

Search companies

German software companies with 51 to 200 employees:

curl -X POST "https://api.superagnt.com/v1/connections/ai-ark/v1/companies" \
  -H "Authorization: Bearer $AGNTDATA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "account": {
      "industries": { "any": { "include": { "mode": "SMART", "content": ["software development"] } } },
      "location": { "any": { "include": ["Germany"] } },
      "employeeSize": { "type": "RANGE", "range": [{ "start": 51, "end": 200 }] }
    },
    "page": 0,
    "size": 10
  }'

Search people, then find their emails

curl -X POST "https://api.superagnt.com/v1/connections/ai-ark/v1/people" \
  -H "Authorization: Bearer $AGNTDATA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contact": { "experience": { "latest": { "title": { "any": { "include": { "mode": "SMART", "content": ["head of sales"] } } } } } },
    "account": { "location": { "any": { "include": ["United States"] } } },
    "page": 0,
    "size": 10
  }'

curl -X POST "https://api.superagnt.com/v1/connections/ai-ark/v1/people/email-finder" \
  -H "Authorization: Bearer $AGNTDATA_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{ \"trackId\": \"$TRACK_ID\", \"webhook\": \"https://api.superagnt.com/webhooks/ingest/$HOOK_ID\" }"

curl "https://api.superagnt.com/v1/connections/ai-ark/v1/people/email-finder/$TRACK_ID/statistics" \
  -H "Authorization: Bearer $AGNTDATA_API_KEY"
curl "https://api.superagnt.com/v1/connections/ai-ark/v1/people/email-finder/$TRACK_ID/inquiries?page=0&size=100" \
  -H "Authorization: Bearer $AGNTDATA_API_KEY"

Look up a profile from an email address

curl -X POST "https://api.superagnt.com/v1/connections/ai-ark/v1/people/reverse-lookup" \
  -H "Authorization: Bearer $AGNTDATA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "search": "person@example.com" }'

13 tools, one per resource and risk

MCP servers and agents on the grouped surface list AI Ark as these tools. Each takes an action, and the ones that work across record types an object. Every operation also keeps its own per-operation name, in the next table, which works on every server. How grouping works: Grouped tools.

All 19 operations

Each operation is a REST path under https://api.superagnt.com/v1/connections/ai-ark and an MCP tool. The per-operation tool name is the one permissions, approvals and usage records use.

Related