ManicTime Server API
You can use ManicTime Server API in order to programmatically access timeline data using Timeline API.
How a script or an application signs in depends on the sign-in system of your server:
- New sign-in system (ManicTime Server v2026.3) - use an API token or an API client. See New sign-in system.
- Old sign-in system - use Windows authentication or a ManicTime username and password. See Old sign-in system.
To see which system your server uses, go to Administration -> User management -> Sign-in methods. If the page shows New sign-in system available, the server uses the old sign-in system. See Sign-in methods.
New sign-in system
On a server with the new sign-in system, the old ways to sign in do not work. The server refuses a username and password at /api/token, and it does not accept Windows authentication for API requests.
Use one of these:
- API token - for a script that uses the API as one user. See API token.
- API client - for an application that users sign in to through the browser. See API client.
Administrators create both on the Developer page.
API token
- Create an API token on the Developer page.
- Send the token in the
Authorizationheader of each API call.
GET https://manictime.example.com/api
Authorization: Bearer mt_api_<token>
Accept: application/vnd.manictime.v3+json
The script has the roles and rights of the user that the token belongs to. If the token is deleted or expired, or the user is archived, the server answers 401 Unauthorized.
API client
An API client uses the OAuth 2.0 authorization code flow with PKCE. The user signs in on the ManicTime Server sign-in page with any enabled sign-in method. The application then calls the API as that user.
Register the application as an API client on the Developer page. You get a client ID. A Web application also gets a client secret.
Get the endpoint URLs from the OpenID Connect configuration of your server:
GET https://manictime.example.com/.well-known/openid-configuration Accept: application/jsonUse
authorization_endpoint,token_endpointandrevocation_endpointfrom the response.Open
authorization_endpointin the browser:GET <authorization_endpoint> ?response_type=code &client_id=<client_id> &redirect_uri=<redirect_uri> &scope=openid+profile+api+offline_access &state=<state> &code_challenge=<code_challenge> &code_challenge_method=S256The
redirect_urimust be one of the redirect URIs of the API client. The server accepts onlyS256ascode_challenge_method.The user signs in. The browser then calls
redirect_uriwith the authorization code in thecodeparameter.Exchange the code for tokens:
POST <token_endpoint> Content-Type: application/x-www-form-urlencoded grant_type=authorization_code&code=<code>&redirect_uri=<redirect_uri>&code_verifier=<code_verifier>&client_id=<client_id>&client_secret=<client_secret>A Native application has no client secret, so leave out
client_secret. A Web application can also send the client ID and the client secret with HTTP Basic authentication.Call the API with the access token:
GET https://manictime.example.com/api Authorization: Bearer <access_token> Accept: application/vnd.manictime.v3+jsonWhen the access token expires, get new tokens with the refresh token:
POST <token_endpoint> Content-Type: application/x-www-form-urlencoded grant_type=refresh_token&refresh_token=<refresh_token>&client_id=<client_id>&client_secret=<client_secret>
An access token is valid for 10 minutes. Each refresh gives a new refresh token. Use the new refresh token for the next refresh, and do not refresh with the same token two times at the same time.
For an MCP client, also request the mcp:tools scope.
Old sign-in system
The sections below are for servers with the old sign-in system.
Authentication - Windows users
When server is configured with Windows users, Kerberos or NTLM is used for authentication. Please use a client HTTP library that supports these protocols.
Authentication - ManicTime users
When server is configured with ManicTime users, OAuth 2.0 is used for authentication. Oauth 2.0 Resource Owner Password Flow is used, where after sending username and password your app gets access token. You use access token in order to make authorized API calls.
You need to follow these steps in order to get and use access token:
1. Get token endpoint URL
2. Get access token
3. Call API
1. Get token endpoint URL
To get token endpoint URL, make HTTP call without authorization headers
GET http://localhost:8080/api
Accept: application/vnd.manictime.v3+json
HTTP/1.1 401 Unauthorized
Content-Type: application/vnd.manictime.v3+json charset=utf-8
WWW-Authenticate: Bearer
{
"links": [
{
"rel": "manictime/token",
"href": "http://localhost:8080/api/token"
}
]
}
2. Get access token
To get access token, call token endpoint URL with username and password
POST http://localhost:8080/api/token
Content-Type: application/x-www-form-urlencoded
Accept: application/vnd.manictime.v3+json
grant_type=password&username=<username>&password=<password>
HTTP/1.1 200 OK
Content-Type: application/json
{
"token": <access_token>
}
3. Call API
You can need to include access token with each API call.
GET http://localhost:8080/api
Authorization: Bearer <access_token>
Accept: application/vnd.manictime.v3+json
HTTP/1.1 200 OK
Content-Type: application/vnd.manictime.v3+json; charset=utf-8
{
"links": [
{
"rel": "self",
"href": "http://localhost:8080/api/"
},
{
"rel": "manictime/timelines",
"href": "http://localhost:8080/api/timelines"
},
{
"rel": "manictime/environments",
"href": "http://localhost:8080/api/environments"
},
{
"rel": "manictime/screenshots",
"href": "http://localhost:8080/api/screenshots"
},
{
"rel": "manictime/clientState",
"href": "http://localhost:8080/api/clientState"
},
{
"rel": "manictime/tagcombinationlist",
"href": "http://localhost:8080/api/tagcombinationlist"
},
{
"rel": "manictime/clientsettings",
"href": "http://localhost:8080/api/clientSettings"
}
]
}