REST API and MCP Server Overview

How the API is organized

Most APIs grow as a pile of separate endpoints that slowly fall out of step with the product. SaaSVisionary takes a different approach. Every operation in the platform, such as creating a contact, moving a deal or booking an appointment, is defined once in a shared action catalog. Each action has:

a permanent name, for example contacts.create
a JSON Schema describing its input
the permissions a caller needs
a description of its effect

There is no second copy of this list for developers. The in-app assistant, the MCP server and the REST API each load their actions from the catalog, which is why a newly released feature is callable everywhere on day one and validates input identically on each.

Base URL: https://app.saasvisionary.com/api/v1

All requests use HTTPS and return JSON.

Plan availability

Surface	Available on
REST API and outbound webhooks	Team and Unlimited
MCP server	Unlimited

Start a 14-day free trial on the Unlimited plan to try both during evaluation.

Authentication with API keys

Create a key

Sign in at https://app.saasvisionary.com.
Open the Developers area.
Create a new API key, choose its scopes and give it a descriptive name, such as “Warehouse sync” or “Support agent”.
Copy the key right away. It is shown only once.

Keys are scoped and revocable. Grant a key only the reach its job needs, and revoke it the moment it is no longer in use or may have leaked.

Send the key

Pass the key as a bearer token in the Authorization header on every request:

Authorization: Bearer YOUR_API_KEY

Store keys in environment variables or a secrets manager. Never commit them to source control or paste them into support tickets.

Check who you are

A GET on the base URL returns the workspace the key belongs to, its scopes and how many actions it can reach. It is a quick way to confirm a key works:

curl https://app.saasvisionary.com/api/v1 \
  -H "Authorization: Bearer $SAASVISIONARY_API_KEY"

Scopes and permissions

Every action carries a permission requirement, and the API enforces it exactly as the app does. Within a workspace, users hold one of three roles: owner, admin or member. A key is capped by two things set when it was made, its scopes and the role behind it, and it cannot exceed either.

Practical guidance:

One key per integration. If a nightly reporting script only reads data, give it read scopes only.
Separate keys for agents. Give an AI agent its own key so you can revoke it without breaking other integrations.
Rotate on staff changes. When someone who created keys leaves, review and rotate them.

Confirm-classified actions

Some actions send messages, spend money or delete data. These are marked as confirm-classified in the catalog. The in-app assistant stops and asks a person before running them. If you build your own agent, use this flag to add a human approval step before those calls.

Discovering actions

You do not need to hard-code a list of endpoints. The catalog is discoverable at runtime.

List the catalog

curl https://app.saasvisionary.com/api/v1/actions \
  -H "Authorization: Bearer $SAASVISIONARY_API_KEY"

The response lists the actions your key can reach, each with its name, a description and a JSON Schema for its input. Use the schema to build forms, validate payloads before sending, or generate typed clients.

Catalog, search, describe, run

A typical integration follows four moves:

Catalog: list what exists.
Search: narrow to the domain you need, such as contacts, deals, calendars or invoices.
Describe: read one action’s schema to see required and optional fields.
Run: call the action.

Action names are permanent, so code written against contacts.create today keeps working as the catalog grows.

Running an action

Every action is a single POST to its name:

POST /api/v1/actions/<action>

The request body is the action’s input as JSON.

Example: create a contact

curl https://app.saasvisionary.com/api/v1/actions/contacts.create \
  --request POST \
  --header "Content-Type: application/json" \
  --header "Authorization: Bearer $SAASVISIONARY_API_KEY" \
  --data '{
    "email": "dev@harborlinecoffee.example",
    "first_name": "Devon",
    "last_name": "Achebe",
    "phone": "+15125550148"
  }'

If the body fails schema validation, the API returns an error describing which field is wrong, so you can fix the request without guessing.

Example: export the workspace

The workspace.export action produces a full data export, the same one available under Settings → Your data in the app. It is useful for backups and migrations:

curl -X POST https://app.saasvisionary.com/api/v1/actions/workspace.export \
  -H "Authorization: Bearer $SAASVISIONARY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Conventional REST resources

For common records such as contacts, deals and tasks, conventional CRUD endpoints with pagination are also available. Use whichever style fits your code; both enforce the same rules.

Rate limits

Each credential has its own request budget. Responses include rate-limit headers so a client can see how much budget remains and when it resets. Current limits are shown in your API settings; contact support if you need higher limits.

Good habits:

Read the rate-limit headers and slow down before you hit zero.
On a 429 response, wait for the indicated retry time, then back off exponentially.
Batch work where an action supports it instead of looping one record at a time.

Outbound webhooks

Instead of polling, you can register HTTPS endpoints and the platform pushes each event to them the moment it occurs, through /api/v1/webhooks or the action catalog.

Deliveries carry an HMAC signature. You see the secret used to sign them a single time, at the moment the subscription is created, so store it then and check each incoming request against it.
Failed deliveries are retried with backoff, and each delivery’s status and error are logged.
The cap is 200 live subscriptions (event plus endpoint pairs) per workspace.

The MCP server

The Model Context Protocol (MCP) is an open standard that lets AI assistants discover and call tools. SaaSVisionary includes an MCP server, so there is nothing to host or proxy yourself. Every action in the catalog is exposed as an MCP tool.

MCP endpoint: shown in your workspace under API settings

The MCP server uses the same bearer API keys, scopes and permission checks as the REST API.

Connect an MCP client

Most MCP-capable assistants and IDEs accept a remote server URL plus a header. A typical configuration looks like this:

{
  "mcpServers": {
    "saasvisionary": {
      "url": "https://app.saasvisionary.com/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

The exact format depends on your client; check its documentation for remote server setup.

tools/list

When the client connects, it calls tools/list. The server responds with the tools your key can reach, each with a name, description and input schema derived from the catalog:

curl -X POST https://app.saasvisionary.com/api/mcp \
  -H "Authorization: Bearer $SAASVISIONARY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

tools/call

To run a tool, the client sends tools/call with the tool name and arguments:

curl -X POST https://app.saasvisionary.com/api/mcp \
  -H "Authorization: Bearer $SAASVISIONARY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "contacts.create",
      "arguments": {
        "first_name": "Luis",
        "phone": "+13055550199"
      }
    }
  }'

In practice your assistant sends these messages for you. The examples show what happens on the wire, which helps when debugging.

Keeping agents safe

Give each agent its own scoped key and revoke it if behavior looks wrong.
Start with read-only scopes and add write access once you trust the workflow.
Add a human approval step for confirm-classified actions that send, spend or delete.
Review the workspace activity log to see what an agent actually did.

Where to get help

Email support@saasvisionary.com with your workspace name, the action name, the request time and the full error response. Remove API keys from anything you send.

FAQ

Which plan do I need for the SaaSVisionary API?

The REST API and outbound webhooks are available on the Team and Unlimited plans. The built-in MCP server is included on Unlimited. Start a 14-day free trial on the Unlimited plan to build and test an integration against both surfaces before paying.

Is the API limited compared with the app?

No. The product and the API are built on one shared action catalog, so any action you can take in the interface is also callable from code, subject to identical validation and permissions. When something new ships, it arrives in the app, the assistant, REST and MCP together.

How do I find the input format for an action?

Call GET /api/v1/actions. Each action in the response includes a JSON Schema describing its required and optional fields. MCP clients get the same schemas through tools/list. You can use them to validate payloads or generate typed client code.

Can an AI agent delete data or send messages without asking?

Actions that send, spend or delete are confirm-classified in the catalog. The in-app assistant always asks a person before running them. For your own agents, use scoped keys, start with read access, and add an approval step for those actions before granting write scopes.

How do I revoke access for an integration?

Open the Developers area in the app and revoke the key the integration uses. Revocation takes effect immediately for both the REST API and the MCP server. Using one key per integration means you can shut off a single tool without disrupting others.

SaaSVisionary API and MCP Server Overview