Migrate to projects

What changes

• Every product request names its project: HTTP paths start with/api/projects/:projectId/, and MCP data tools take a projectId argument.
• Your existing data moved, unchanged, into one project per organization. That project is fixed: legacy routes always read and write it, even if you later make another project the default.
• Access is granted per project. Organization owners reach every project; other members and API keys need a project grant with the viewer, editor, or admin role.
• Studio URLs include the project slug, for example /studio/:projectSlug/contacts.
• Tracking snippets and SDKs keep working without changes.

Deprecation and sunset

While a legacy route still works, every response carries three headers. The dates are fixed for your environment and do not move:

Deprecation: @<enablement time, Unix seconds>
Sunset: <fixed HTTP date, at least 90 days after enablement>
Link: <https://usereachout.com/docs/project-migration>; rel="deprecation"; type="text/html"

MCP tools called in legacy mode return the same information as a structured legacy object with deprecatedAt, sunsetAt, migrationGuide,operationId, and projectId.

Legacy routes are removed only after the Sunset date and 14 consecutive days in which no legacy route was used successfully. Any successful call restarts that 14-day window. After removal, a legacy HTTP route returns 410 LEGACY_ROUTE_REMOVED, and a legacy MCP call returns the structuredLEGACY_ROUTE_REMOVED error without running the operation.

Find your project ID

List the projects your credentials can access:

GET /api/projects
Authorization: Bearer <api_key>

{
  "projects": [
    { "id": "project_…", "slug": "legacy-…", "name": "…", "status": "active", "isDefault": true }
  ]
}

Organization owners see every project; an API key or member sees only the projects it has a grant for. Use the stable id in API paths; the slug is for Studio URLs. Over MCP, delegated users call list_projects, and organization API keys call get_organization_overview.

HTTP routes

For almost every route, insert /projects/:projectId after /api and keep the same method. Each project-scoped request checks that the project exists in your organization and that your credential has a sufficient role on it.

- GET /api/contacts?limit=50
+ GET /api/projects/project_…/contacts?limit=50

Three routes change more than the prefix:

• POST /api/contacts/import becomes the contact-import resource,POST /api/projects/:projectId/contact-imports, with its own request format.
• GET /api/dashboard/stats becomes GET /api/projects/:projectId/dashboard/stats.
• The live analytics stream at /api/analytics/stream is served only asGET /api/projects/:projectId/analytics/stream.

Analytics

Assets

Automations

Campaigns

Contact fields

Contact imports

Contacts

Dashboard stats

Data sources

Email domains

Insights

Recipient list binding

Segments

Templates

Tracking clients

API keys

Every API key that existed at migration received the admin role on your migrated project, so existing integrations keep their access to it. Keys are not granted new projects automatically: grant each one explicitly.

POST /api/api-keys/:keyId/projects
{ "projectId": "project_…", "role": "editor" }

PATCH  /api/api-keys/:keyId/projects/:projectId   { "role": "viewer" }
DELETE /api/api-keys/:keyId/projects/:projectId

There is no all-projects grant, and linking a key to a user never widens what the key can reach. Over MCP, a delegated user manages grants with grant_api_key_project, list_api_key_project_grants, and revoke_api_key_project.

MCP

• Pass projectId to every data tool, for examplelist_contacts or get_analytics_overview. There is no stored active project and no switch_project tool.
• An organization API key that omits projectId runs in legacy mode against your migrated project and receives the legacy notice described above. This mode is removed with the HTTP routes.
• Project management and grant tools require a delegated user through OAuth; an API key receivesMCP_USER_DELEGATION_REQUIRED. See the MCP reference.

Tracking

No change is needed. Snippets and SDKs keep sending their tracking client ID, and ReachOut resolves the project from it. A tracking client cannot move between projects once it has received events; to track a site in another project, create a new tracking client there and install its snippet.

Errors

Migration checklist

1. Call GET /api/projects and record the project ID each integration should use.
2. Grant each API key the projects and roles it needs.
3. Rewrite HTTP paths using the tables above and add projectId to MCP tool calls.
4. Handle 404, 403, 409, and 503 as described in Errors.
5. Confirm your traffic no longer carries Deprecation headers or MCP legacy notices.