Help center

Connect your script to a Profile over the local API

Where the local API lives, how to read its port and token, and the five calls that start a Profile, attach Puppeteer or Playwright over CDP, and stop it.

Agilelogin runs a small HTTP API on this computer while the app is unlocked. A script reads the port and a session token from two files, asks the API to start a Profile, and attaches to the browser it launched through the Chrome DevTools Protocol (CDP); this article covers that path and what the API does not do.

Applies to: launcher 0.1.0, API version v1. The complete API reference is published after the first release; until then, use only the calls shown here.

Where does the service live?

  • The API listens on 127.0.0.1 only, on a port the operating system picks at random each time the service starts. There is no remote access and no setting that binds it to another address.
  • When the service starts it writes two files into the app’s data folder, and a script reads both before every connection:
    • api_port — the port number as plain text.
    • api_token — a 64-character hexadecimal session token, new on every start. On Windows it relies on the default user permissions of %APPDATA%; on macOS the file is readable by your user only.
  • The data folder is %APPDATA%\com.agilelogin.app\ on Windows and ~/Library/Application Support/com.agilelogin.app/ on macOS.
  • Locking the app, by hand or after 15 minutes without input, stops the service and deletes both files. A script then sees a refused connection, not a 401. After unlock the service starts again with a new port and a new token, so never cache them.
  • Every route except GET /api/v1/status needs the header Authorization: Bearer <contents of api_token>. A missing or wrong token returns 401 with a body of the form { "error": { "kind": "unauthorized", "message": "…" } }.
  • All paths start with /api/v1. Request and response fields are camelCase.

The minimal flow

  1. Read api_port and api_token from the data folder.
  2. POST /api/v1/profiles/{id}/start with the Bearer header. A 200 response carries cdpReady and cdpEndpoint, for example ws://127.0.0.1:<port>/devtools/browser/<guid>.
  3. Attach: puppeteer.connect({ browserWSEndpoint: cdpEndpoint }) or playwright.chromium.connectOverCDP(cdpEndpoint).
  4. GET /api/v1/profiles/{id}/status returns status (idle, running or error) and the current cdpEndpoint, or null when the browser is not running.
  5. POST /api/v1/profiles/{id}/stop closes the browser.

Things the flow depends on:

  • cdpEndpoint is the address the kernel itself reports; its port changes on every start. Read it from the response, never build it by hand.
  • start can return 200 with cdpReady: false and cdpEndpoint: null when the browser launched but CDP was not ready within about ten seconds. Check cdpReady before you connect.
  • GET /api/v1/profiles/{id} returns the Profile without cdpEndpoint; use status for that.
  • There are no events or WebSocket on this API. Poll status to follow state changes. The one WebSocket you use belongs to the kernel’s CDP, not to this API.
  • Starting a Profile that is already running returns 422 with the message Profile is already running.
  • With Launch lock, start can return 409 when the same Profile is open on another device signed in to the same account. The message begins with the machine-readable prefix PROFILE_IN_USE_ELSEWHERE:. Launch lock is advisory: it coordinates well-behaved clients and is not access control, and a client that cannot obtain the lease, for example while offline, still starts.
  • GET /api/v1/status needs no token and returns the app version and apiVersion. Use it as a health check.

What else the API covers

Stable in this release, with the full request shapes in the reference after launch:

  • Profiles: list, create, read, update and delete Profiles, batch-delete, counts by state, start, stop and status.
  • Proxies: list, create, bulk-create, update and delete proxies, and run a connectivity and exit-IP check on one.
  • Cookies, under a Profile: read a summary, clear, import (Netscape, JSON or EditThisCookie), export, and copy to another Profile.
  • Groups: list, create and delete.
  • Extensions: list and delete imported extensions, import one from a local path (crx, zip or unpacked folder), and read or set which extensions a Profile loads.
  • Account: read the account state, register, sign in and out, list and revoke device sessions, request a password email, resend verification, and set a password. The sign-in response carries no access or refresh token. Social sign-in with Google or GitHub is not available over the API; it needs a person at the keyboard and exists only in the app window.

Present in this release but their shape may change after the first release, so they are listed here without usage: kernel status, bulk import and export (asynchronous, with an operation to poll or cancel), migrating Profiles to another kernel version, resetting a Profile’s login state, the clone check, the license endpoints the app uses for itself, and preparing a machine for imaging.

Errors

  • The body is { "error": { "kind": "<snake_case>", "message": "<English sentence>" } } and the status code follows the category: 400, 403, 404, 409, 422, 500, 502.
  • When the framework rejects a request before it reaches a route, for example a JSON body that does not parse, the reply is plain-text 422, not that shape.
  • Messages are English and not localised. The error body’s fields may change after the first release.

What a token can do

A local process that reads api_token can do everything this API can do as this computer: import and export cookies, start and stop browsers, and sign this computer’s account in or out. The boundary is that the file is readable by the current operating-system user only. There is no per-script permission and no read-only token. The sign-in response does not pass access or refresh tokens through, so a process can act as this computer but cannot carry the credentials elsewhere.

Not provided

  • No remote access: the service listens on 127.0.0.1 and nothing can change that.
  • No cloud API: this API exists only on the computer where the app is installed. The account service does not expose an interface to third parties.
  • No event push and no WebSocket on this API.

Questions about the API go to support@agilelogin.com.