Skip to main content

​
Using your API key

All API endpoints are authenticated using the API key you have been provided. Pass the API key in the Authorization header: 
Authorization: Bearer sk_xxx

​
Creating a project

Projects are the core resource in the Specular API. Each project represents a full backend with an isolated database and deployment. You should create a new project for each of your user’s projects. When a new project is created, an initial branch is also created and returned in the response. When a user starts a new project on your platform, call the create project endpoint with a name: 
POST https://api.specular.dev/projects/

{
  "name": "Test project"
}
This request might take a few seconds to process as a full development environment is spun up. The response will contain details on your newly created project as well as an initial branch which is created automatically. 
{
  "project": {
    "id": "proj_XNZEFS5s8T9nB5cFwqE9g"
    // ...
  },
  "branch": {
    "id": "branch_7M9xWC4fpZbfgt7nA2Kyu",
    "mcpUrl": "https://wqpn3bx5234cum6uuwj3ranzphzngsu6.mcp.specular.dev",
    "appUrl": "https://5z668kwkda5g4gbykrfyhqz8spcpvcs5.app.specular.dev"
    // ...
  }
}

​
Using your own Git repo

By default, we will manage the code for each project. You can also bring your own Git repo, to which we will commit and push changes as they are made. If you want to provide your own Git repo, you can pass the details to connect to it as shown below. Before doing so, you should create an initial development branch for us to push to: 
{
  "name": "Test project",
  "git": {
    "remoteUrl": "https://github.com/example/repo-name.git",
    "username": "USERNAME",
    "password": "PASSWORD",
    // Git branch from which production deployments should happen
    "mainBranch": "main",
    // Git branch our coding agent will push changes to
    "initialBranch": "dev-branch-1",
    // Optional: a path in the repository where the backend code should be comitted
    "path": "/backend"
  }
}

​
Connecting your coding agent

After having created your project, you will receive an mcpUrl associated with the initial branch created automatically. You should connect your coding agent to this MCP to let it build and evolve the backend it needs through natural language prompts. Once the build is complete, it will return an OpenAPI schema that your coding agent can use as a reference for how to integrate with the backend. The MCP has a simple interface consisting of two endpoints:
  • make_change which accepts a natural-language prompt guiding our coding agent to make changes to the backend. This will run asynchronously and get_status should be used to check if the building is done.
  • get_status which returns the status of the current build. It will also return an OpenAPI spec for the backend which describes the schema of the built API. Your coding agent can use this to integrate with the API.
If you prefer not having your coding agent poll get_status through the MCP, you can also poll the API to retrieve the same information: 
GET https://api.specular.dev/branches/branch_7M9xWC4fpZbfgt7nA2Kyu

{
  "branch": {
    "id": "branch_7M9xWC4fpZbfgt7nA2Kyu",
    "state": "building",
    "openApiSpec": "openapi: 3.0.0...",
    "mcpUrl": "https://wqpn3bx5234cum6uuwj3ranzphzngsu6.mcp.specular.dev",
    "appUrl": "https://5z668kwkda5g4gbykrfyhqz8spcpvcs5.app.specular.dev"
  }
}
The state will be building if a change is currently being built and idle when it’s done.

​
Managing environment variables

Environment variables let you configure your backend with API keys, secrets, and other configuration values. Each branch has its own set of environment variables that are available to your coding agent and running application. When creating a new branch, existing production environment variables are automatically copied to it, giving you a starting point that matches production.

​
Setting environment variables

To set or update environment variables for a branch: 
PUT https://api.specular.dev/branches/branch_7M9xWC4fpZbfgt7nA2Kyu/env-vars

{
  "vars": [
    {
      "name": "STRIPE_SECRET_KEY",
      "value": "sk_test_..."
    },
    {
      "name": "SENDGRID_API_KEY",
      "value": "SG...."
    }
  ]
}
The sandbox will automatically refresh to apply the new environment variables if it’s currently active.

​
Listing environment variables

Retrieve all environment variables for a branch: 
GET https://api.specular.dev/branches/branch_7M9xWC4fpZbfgt7nA2Kyu/env-vars

{
  "environmentVariables": [
    {
      "id": "env_xyz",
      "name": "STRIPE_SECRET_KEY",
      "value": "sk_test_...",
      "createdAt": "2024-01-15T10:30:00Z",
      "updatedAt": "2024-01-15T10:30:00Z"
    }
  ]
}

​
Deleting environment variables

Remove an environment variable: 
DELETE https://api.specular.dev/branches/branch_7M9xWC4fpZbfgt7nA2Kyu/env-vars?name=STRIPE_SECRET_KEY

​
Environment variables in production

When you merge a branch to production, its environment variables are automatically merged to production as well, overwriting any existing values with the same name. This ensures your production deployment uses the configuration you tested in development.

​
Refreshing a branch

You can refresh a branch to restart the application with the latest code changes and environment variables: 
POST https://api.specular.dev/branches/branch_7M9xWC4fpZbfgt7nA2Kyu/refresh
This is useful when you’ve made changes directly to your git repository, such as reverting commits. Note that the refresh endpoint is called automatically when you update environment variables.

​
Merging and deploying projects

Once your coding agent has built the backend you need, you can merge it to production with a single API call. This will validate the changes, merge to your main branch, apply database migrations, and deploy your backend to production infrastructure.

​
Triggering a deployment

To deploy a branch to production, call the merge endpoint: 
POST https://api.specular.dev/branches/branch_7M9xWC4fpZbfgt7nA2Kyu/merge
This operation runs asynchronously and typically takes up to a minute to complete. The endpoint will return immediately with a 202 Accepted status: 
{
  "message": "Merge initiated",
  "branchId": "branch_7M9xWC4fpZbfgt7nA2Kyu"
}

​
Monitoring deployment progress

You can poll the branch status to check if the merge is complete: 
GET https://api.specular.dev/branches/branch_7M9xWC4fpZbfgt7nA2Kyu
The branch state will be:
  • merging - Deployment is in progress
  • merged - Deployment completed successfully
  • idle - Branch has not been merged, or there was an error

​
Accessing your production API

After a successful merge, your production API URL will be available in the project details: 
GET https://api.specular.dev/projects/proj_XNZEFS5s8T9nB5cFwqE9g

{
  "project": {
    "id": "proj_XNZEFS5s8T9nB5cFwqE9g",
    "name": "Test project",
    "productionUrl": "https://abcd1234.execute-api.eu-central-1.amazonaws.com/prod",
    // ...
  }
}
You can now use this production URL to make requests to your deployed backend. The API will be identical to what you tested in the development environment.