Profiles over the API: list, edit, one-time, cookies, export

A script can pick profiles from a long list, change them, open a one-time profile in one request, read and load cookies and move profiles as files. Every call needs the token from For developers.

Pick profiles out of the list

profile/list and browser/list take arguments in the address. With none, the answer is the whole list in the usual order, so older scripts see no difference.

The answer always carries total, page and pageSize next to list. An argument the API does not know is not refused but named in ignored, so a typo shows up instead of an empty list.

A long list of ids goes in the body of POST profile/list instead of the address. Each row carries notes, status, updatedAt, launches, runTimeMs and openSince.

Filter: ids, group, groupId, tags, tagsMode, search, running, passwordProtected, scenario, template, status, proxy
Dates: createdFrom, createdTo, updatedFrom, updatedTo, usedFrom, usedTo
Order: sort: name, createdAt, updatedAt, lastUsedAt, launches, runTime, group; order: asc or desc
Pages: page from 1, pageSize from 1 to 100; fields picks the columns
Example: GET /api/v1/profile/list?tags=ads&sort=lastUsedAt&order=desc&pageSize=50

search looks in the name, group, note, tags, proxy address and in the id from six characters. With fields it looks only in the fields you asked for. tagsMode all wants every tag you name, any wants one of them.

Change a profile

POST profile/update changes only the fields you send, with the checks of the profile window: shared to start only, a profile password, values the window refuses.

Request: { profileId, name: Shop-02, proxy: { port: 8081 } }
Answer: { code: 0, data: { changed, profile, notSent, localOnly } }
Open profile: needsRelaunch, pendingKeys: apply at the next start
This computer only: fingerprint (values set by hand), login (the site login), twoFactorKey (the 2FA key)

proxy, fingerprint and login change part by part; null removes them. A proxy keeps its password on the same server. A failed check changes nothing; a fingerprint refusal lists fitting values in data.allowed.

A one-time profile in one request

POST profile/quick creates a profile and opens it at once, like the One-off profile button in the window. It takes fingerprintTemplate, proxy or proxyId, geolocation, webrtc, cookies, startUrl, headless and name.

The answer is the one browser/start gives, plus temporary and profileId. Once closed, it is deleted whole, never into the recycle bin, and one left by a killed program is cleaned up at the next start.

It stays on this computer but takes a place in your plan while open.

The proxy is checked before the launch

Before every launch the proxy is checked. A refusal carries the reason in data.reason: proxy_silent, proxy_refused, proxy_not_found, proxy_auth, exit_country_unknown or exit_services_blocked, and msg says it in words.

A launch that opened carries data.exit: the exit IP, the country and whether it was checked now; a country taken from the last check comes with an empty IP. For a slow proxy send proxyWaitSec from 5 to 60 seconds; the default is 12.

Cookies of a profile

GET profile/cookies reads the cookies of one profile, all of them or one domain with its subdomains, as JSON or in the Netscape text format. POST profile/cookies/export does the same for up to 100 profiles and answers for each one.

POST profile/cookies/import takes cookies as a list or as text in JSON, Netscape or Firefox form, the same ways Import cookies takes a file in the window. The body may reach 16 MB; expired cookies are counted and left out.

Cookies stay on this computer. They never go to our server, and the MCP server has no cookie tools, so an AI assistant does not see your sign-ins.

The profile is	Reading	Loading
Open, either engine	At once	At once, into the open browser
Closed, built-in engine	At once	At once
Closed, ARMANOS Browser	Opened hidden for reading, with no sites, no network and no extensions	Queued: they enter before the first page of the next start

Reading does not count as a launch

The hidden opening for reading adds no launch to the history, does not move Last used and does not send the session to your sync folder.

Export and import profiles

POST profile/export takes up to 100 profileIds. With kind settings the settings come right in the answer, without proxy passwords and 2FA keys unless you send includeCredentials; with kind full each closed profile goes into an .armanos archive with its session, locked by archivePassword.

POST profile/import takes settings in data, or the names of archive and settings files in files. Both work profile by profile and answer for each one.

Archives lie in the ARMANOS folder in Downloads, or in exports inside ARMANOS_OUT_DIR in server mode, and a request never names a path. Settings whose profile id is already taken here come back with identityChanged, because to websites it is now a different machine.

The WebRTC mode of a new profile

profile/create and profile/quick take webrtc with mode and, for custom, ip: an internet address, IPv4 or IPv6. The answer of profile/create always carries webrtc.

Names from other programs: altered, mask or ip is proxy here, manual is custom, local or natural is real, udpDisabled or disableUDP is noudp, and disabled is off.

proxy: Proxy address, the default
custom: My address, needs ip
real: Real
noudp: No UDP
off: Off

A wrong value is refused with webrtc.mode, webrtc.empty, webrtc.notIp, webrtc.private or webrtc.special in msg, and data.message says why in words.

Codes an answer can carry

A refusal comes as a code in msg, not a translated sentence, so a script can branch on it.

profile_password_required: The profile is closed with a password: open it first
profile_not_yours: A colleague shared this profile with you: only its owner or an admin can delete it or export it to a file
share_run_only: The profile is shared with you to start only: changes and cookies need the edit level
share_move_full_only: Moving a shared profile to another group needs full access
unknown_field: Unknown field: data.field names it, nothing is saved
share_fp_values_own_only: Fingerprint values set by hand change on your own profile only
profile_running: Full export and hidden reading need the profile closed
profile_busy: The profile is open on another machine
bad_param: An argument has a wrong value; data.param names it
payload_too_large: The body is over the limit for this call
quota: The plan has no place for one more profile

What this does not do

It does not hand profiles to another account. Export and import move files; the account stays yours.
It does not write a file wherever a request says.

Where this is decided

Each line names the stand that checks it.

Filters, order and pages of the list, the same rule in the local API and on the server: packages/shared/test/отбор-профилей.js, apps/desktop/test/api-список.js
A one-time profile over the API is deleted after closing and never reaches the account: apps/desktop/test/api-одноразовый.js, apps/desktop/test/api-одноразовый-живьём.js
Cookies of open and closed profiles, and the hidden reading without network: apps/desktop/test/api-куки.js, apps/desktop/test/api-куки-закрытого-живьём.js
Export and import answer per profile and never write outside their folder, and server mode takes that folder from ARMANOS_OUT_DIR: apps/desktop/test/api-выгрузка-загрузка.js · apps/desktop/test/режим-сервера.js
Every call that takes a profile id refuses a closed profile: apps/desktop/test/api-двери-за-паролем.js
Changes by a script or over MCP take the window's way: apps/desktop/test/api-правка.js, apps/desktop/test/api-правка-живьём.js, apps/desktop/test/api-правка-другие-ходы-живьём.js

Questions

Why did a filter return nothing?: Look at ignored in the answer: a mistyped argument is named there, not applied.
Does a change reach my other computers?: Yes, except fields listed in localOnly.

Next to this

Try it with one script

The free plan gives two profiles, with no time limit and no card.

Download opens at launch Knowledge base