{"openapi":"3.1.0","info":{"title":"Clockodo (BYOK) API","version":"0.1.0","description":"Clockodo (BYOK) lets an AI assistant read your own Clockodo data through the Clockodo API with a key you supply (Clockodo API key). Read-only: 8 tools (get_current_user, list_time_entries, get_running_clock, list_customers, list_projects, list_services, list_users, list_teams). The BYOK key travels with each request, is used for that one call only and is never stored, logged or cached; it is only...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-clockodo.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-clockodo/docs"},"termsOfService":"https://connectorbay.com/byok-clockodo/terms"},"servers":[{"url":"https://byok-clockodo.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-clockodo/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/get_current_user":{"post":{"operationId":"get_current_user","summary":"Show the Clockodo user the API key belongs to: name, email, role, team, language, time zone and start date. Use for \"Whi","description":"Show the Clockodo user the API key belongs to: name, email, role, team, language, time zone and start date. Use for \"Which Clockodo user am I connected as\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"get_current_userArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_time_entries":{"post":{"operationId":"list_time_entries","summary":"List time entries (and lump-sum entries) between two moments with customer, project, service, user, text, start, end and","description":"List time entries (and lump-sum entries) between two moments with customer, project, service, user, text, start, end and duration in seconds. Both time_since and time_until are required; paged. Use for \"What time entries were booked in Clockodo last week\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"time_since":{"description":"Start of the period, ISO 8601 with Z, for example 2026-03-01T00:00:00Z.","maxLength":30,"title":"Time Since","type":"string"},"time_until":{"description":"End of the period, ISO 8601 with Z, for example 2026-03-08T00:00:00Z.","maxLength":30,"title":"Time Until","type":"string"},"items_per_page":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"How many records per page (1 to 1000).","title":"Items Per Page"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"required":["time_since","time_until"],"title":"list_time_entriesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_running_clock":{"post":{"operationId":"get_running_clock","summary":"Show the time entry that is currently running for the key's user (or a given user id) and the last stopped one. Use for ","description":"Show the time entry that is currently running for the key's user (or a given user id) and the last stopped one. Use for \"Is my Clockodo clock running right now\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"users_id":{"anyOf":[{"type":"integer"},{"type":"null"}],"default":null,"description":"User id to check; omit for the key's own user.","title":"Users Id"}},"title":"get_running_clockArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_customers":{"post":{"operationId":"list_customers","summary":"List customers with number, active flag, billable default and note. Paged. Use for \"Which customers exist in Clockodo\".","description":"List customers with number, active flag, billable default and note. Paged. Use for \"Which customers exist in Clockodo\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"items_per_page":{"anyOf":[{"maximum":5000,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"How many records per page (1 to 5000).","title":"Items Per Page"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"title":"list_customersArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_projects":{"post":{"operationId":"list_projects","summary":"List projects with customer id, number, active and completed flags, deadline, start date, subproject count and budget se","description":"List projects with customer id, number, active and completed flags, deadline, start date, subproject count and budget settings. Paged. Use for \"Which projects are active in Clockodo and when are they due\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"items_per_page":{"anyOf":[{"maximum":5000,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"How many records per page (1 to 5000).","title":"Items Per Page"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"title":"list_projectsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_services":{"post":{"operationId":"list_services","summary":"List services (activity types that time is booked against) with number, active flag and note. Paged. Use for \"What servi","description":"List services (activity types that time is booked against) with number, active flag and note. Paged. Use for \"What services can I book time on in Clockodo\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"items_per_page":{"anyOf":[{"maximum":5000,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"How many records per page (1 to 5000).","title":"Items Per Page"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"title":"list_servicesArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_users":{"post":{"operationId":"list_users","summary":"List the users of the account with email, role, team, active flag, start and exit date. Paged. Use for \"Who works in our","description":"List the users of the account with email, role, team, active flag, start and exit date. Paged. Use for \"Who works in our Clockodo account\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"items_per_page":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"How many records per page (1 to 1000).","title":"Items Per Page"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"title":"list_usersArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_teams":{"post":{"operationId":"list_teams","summary":"List teams with leader user id and member user ids. Paged. Use for \"What teams are set up in Clockodo\".","description":"List teams with leader user id and member user ids. Paged. Use for \"What teams are set up in Clockodo\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"items_per_page":{"anyOf":[{"maximum":1000,"minimum":1,"type":"integer"},{"type":"null"}],"default":100,"description":"How many records per page (1 to 1000).","title":"Items Per Page"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"}},"title":"list_teamsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}