> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.taktoria.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.taktoria.com/_mcp/server. # Create Objective POST https://api.taktoria.com/api/v1/objectives Content-Type: application/json Anybody may create an objective, for anybody in the workspace and any of its teams: a key, or a signed-in session as its person, who is then its creator, who may always see and change it, whoever it belongs to. A Viewer of OKR Hub creates none (`403 viewer_only`). Its key results may come with it in `keyResults` (which needs `keyResults:write` too), or be added afterwards with `createKeyResult`. The activity feed says it was created, for a key under the name of whoever made the key. Reference: https://docs.taktoria.com/api-reference/okr/create-objective ## Authentication - `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer `, where token is your auth token. ## Servers - `https://api.taktoria.com/api/v1` (Production, default) - `http://localhost:3000/api/v1` (Local) ## Request ### Body (application/json) This endpoint expects a CreateObjectiveRequest. - `title` (string, required) — Trimmed; never blank, at most 500 characters. - `year` (integer, required) — The fiscal year, 2000 to 2100. - `description` (string, optional) - `period` (enum, optional) - Allowed values: `QUARTERLY`, `ANNUAL` - `quarter` (integer, optional) - `visibility` (enum, optional) — Public objectives are browsable by everyone in the workspace. Private ones are visible to their owner, the members of the owning team, and whoever created them, whoever they belong to. The owners of its key results see it too. - Allowed values: `PUBLIC`, `PRIVATE` - `weight` (double, optional) — 0.01 to 100; defaults to 1. - `draft` (boolean, optional) — Defaults to false. - `sortOrder` (integer, optional) — Its place in the workspace's order; after every other objective when left out. - `teamId` (string, optional) - `ownerUserId` (string, optional) - `keyResults` (list of CreateKeyResultRequest, optional) — Its key results, at most 50, made with it in this order; each as `createKeyResult` takes one, a first `score` recorded as a check-in. Sending any needs the `keyResults:write` scope as well. An owner from outside the workspace refuses the whole objective. ## Response ### 200 - `id` (string, required) - `organizationId` (string, required) - `title` (string, required) - `period` (enum, required) - Allowed values: `QUARTERLY`, `ANNUAL` - `year` (integer, required) — The fiscal year, 2000 to 2100, named by the year its Q1 falls in. - `visibility` (enum, required) — Public objectives are browsable by everyone in the workspace. Private ones are visible to their owner, the members of the owning team, and whoever created them, whoever they belong to. The owners of its key results see it too. - Allowed values: `PUBLIC`, `PRIVATE` - `weight` (double, required) — Relative weight when objectives roll up into an average, 0.01 to 100. One carrying twice the weight moves the average twice as much. - `keyResults` (list of KeyResult, required) - `draft` (boolean, required) — Still being worked out, not yet agreed. A label only: a draft is seen, scored, rolled up and checked in on like any other. - `sortOrder` (integer, required) — Its place in the workspace's order of objectives, which is set by hand and which every list follows within a period. - `archived` (boolean, required) - `createdAt` (datetime, required) - `updatedAt` (datetime, required) - `description` (string, optional) - `quarter` (integer, optional) — 1-4 for a quarterly objective, absent for an annual one. - `team` (OrgTeamRef, optional) — The team it belongs to. Absent, with `owner`, for an objective with no owner. - `teamId` (string, optional) - `owner` (User, optional) — The person it belongs to. Absent, with `team`, for an objective with no owner. - `ownerUserId` (string, optional) - `score` (double, optional) — The weighted average of its key results' grades, or absent when none has been scored. Absent rather than 0.0 on purpose: an unscored objective has not failed, and a zero would say it had. ## Errors ### 403 Forbidden Error Refused, and `error.code` says why. On an app's write endpoints, a signed-in session is refused `viewer_only` when the person is a Viewer of the app (they read it, and change nothing in it), and `seat_required` without a seat on it; a key is never either. Beyond those: `admin_required` when the change is an admin's (an app admin's for an app's admin powers, a workspace admin's for the workspace's settings), `forbidden` when the person may not change this one thing, `read_only_session` for a change only a key makes, `person_required` for what only a signed-in person does through their own account elsewhere (exporting a LaunchCal artifact to their docs tool), which a key cannot, `insufficient_scope` for a key without the scope, and `google_sign_in_required` for a session the workspace's Google rule turns away. Nothing was done. - `error` (ErrorDetail, required) ### 402 Subscription Required Error The organization has no subscription for the app that lets it in: active, trialing or past due. One that is unpaid (Stripe stopped retrying a failed payment), paused, incomplete or cancelled answers this too, and the message says which: an unpaid app is locked until a workspace admin updates the payment details. `details.status` is the app's subscription status (null with none), and `details.paymentIssue` is `unpaid`, or `payment_failed` for an incomplete one whose first payment failed, as `paymentIssue` on `GET /subscription` reckons it; null when a payment is not why. - `error` (ErrorDetail, required) ### 422 Validation Error - `error` (ErrorDetail, required) ### 429 Too Many Requests Error Rate limited (`rate_limited`): the key, the signed-in person, the workspace or an expensive endpoint's own budget is used up for now. `Retry-After` says how many seconds to wait, and `details` names the `policy`, its `limit`, `windowSeconds` and `retryAfter`. Every answer to an authenticated request carries the IETF `RateLimit-Policy` and `RateLimit` headers, so a client can slow down before it gets this. Nothing was done; wait and send it again. See "Rate limits". - `error` (ErrorDetail, required) ## Types ### CreateKeyResultRequest Owners must be members and teams of the workspace; an id from anywhere else is refused with a 422, and `details.unknown` names it: nobody is dropped. The title is trimmed and never blank (at most 500 characters). - `title` (string, required) - `score` (double, optional) — A first score, 0.0 to 1.0. It is recorded as a check-in by the caller (a key's maker, for a key), as setting one later is. - `weight` (double, optional) — 0.01 to 100; defaults to 1. - `priority` (enum, optional) — Defaults to P2. - Allowed values: `P0`, `P1`, `P2`, `P3` - `draft` (boolean, optional) — Defaults to false. - `sortOrder` (integer, optional) — Its place among its objective's key results; after the others when left out. - `ownerUserIds` (list of string, optional) - `ownerTeamIds` (list of string, optional) ### KeyResult A measurable result that grades its objective. It has its own weight, priority and owners, who need not be the objective's: the people and teams doing the work, who may check in on it and grade it. - `id` (string, required) - `objectiveId` (string, required) - `title` (string, required) - `weight` (double, required) — Relative weight within its own objective, 0.01 to 100. - `priority` (enum, required) — A key result's priority, and the dimension scores are averaged by, so a workspace can see how it did on what mattered most rather than only in aggregate. Objectives have none: a priority's average takes each objective on its key results of that priority alone, with the objective's own weight. - Allowed values: `P0`, `P1`, `P2`, `P3` - `draft` (boolean, required) — Still being worked out, not yet agreed. A label only: a draft is seen, scored, rolled up and checked in on like any other. - `sortOrder` (integer, required) — Its place among its objective's key results, lowest first. - `ownerUserIds` (list of string, required) — Members of the workspace who own it, directly. - `ownerTeamIds` (list of string, required) — Teams of the workspace that own it; their members count as owners. - `createdAt` (datetime, required) - `updatedAt` (datetime, required) - `score` (double, optional) — Google-style grade from 0.0 to 1.0, or absent until it has been scored. 0.7 and up is delivered for an ambitious goal, 0.4 to 0.7 is progress, and under 0.4 is missed. A **Final** grade set on the scorecard is the score. Until there is one, the score is the newest of the key result's other scorecard grades and its latest check-in. A score reset on the scorecard (`noScore`) empties that cell only and leaves this alone. It is what the dashboard's lists show, and what the objective's `score` rolls up. - `lastCheckInAt` (datetime, optional) — When it was last checked in on: its newest check-in's `recordedAt`, so a check-in recorded late counts at its date. Absent if it has never been checked in on. How long it has gone quiet. - `metric` (KeyResultMetric, optional) — The connected metric that drives its score, absent if none. Each number the metric hears becomes a check-in, and a person's own check-in stands only until the metric next moves. Sources are set up on the key result's page in the app, not through the API. ### OrgTeamRef An organizational team such as Eagles or Ravens. - `id` (string, required) - `name` (string, required) ### User A person in a Taktoria organization. - `id` (string, required) - `name` (string, required) - `email` (string, required) - `image` (string, optional) — Their picture: one uploaded on the account page, or else their Google profile picture, brought in when they sign in with Google. ### ErrorDetail - `code` (string, required) — A stable machine-readable code such as `not_found`. - `message` (string, required) - `details` (any, optional) ### KeyResultMetric The metric a key result follows, as anybody who may see the key result sees it. Never its secret, token or address. - `name` (string, required) — What the number is, as the history names it, such as "Weekly active teams". - `kind` (enum, required) — How a metric hears its number. - Allowed values: `WEBHOOK`, `PULL`, `TICKETING` - `paused` (boolean, required) — Paused, it records nothing until somebody resumes it. ## Examples **Request** ```json { "title": "Make onboarding effortless", "year": 2026, "quarter": 3, "keyResults": [ { "title": "Median time to first launch under 10 minutes", "priority": "P1" }, { "title": "90% of new workspaces invite a second person", "weight": 2 } ] } ``` **Response** ```json { "id": "obj_7f3a", "organizationId": "org_1", "title": "Make onboarding effortless", "period": "QUARTERLY", "year": 2026, "visibility": "PUBLIC", "weight": 1, "keyResults": [ { "id": "kr_1", "objectiveId": "obj_7f3a", "title": "Median time to first launch under 10 minutes", "weight": 1, "priority": "P1", "draft": false, "sortOrder": 0, "ownerUserIds": [], "ownerTeamIds": [], "createdAt": "2026-07-01T12:00:00Z", "updatedAt": "2026-07-01T12:00:00Z" }, { "id": "kr_2", "objectiveId": "obj_7f3a", "title": "90% of new workspaces invite a second person", "weight": 2, "priority": "P2", "draft": false, "sortOrder": 1, "ownerUserIds": [], "ownerTeamIds": [], "createdAt": "2026-07-01T12:00:00Z", "updatedAt": "2026-07-01T12:00:00Z" } ], "draft": false, "sortOrder": 4, "archived": false, "createdAt": "2026-07-01T12:00:00Z", "updatedAt": "2026-07-01T12:00:00Z", "quarter": 3 } ``` **SDK Code** ```python import requests url = "https://api.taktoria.com/api/v1/objectives" payload = { "title": "Make onboarding effortless", "year": 2026, "quarter": 3, "keyResults": [ { "title": "Median time to first launch under 10 minutes", "priority": "P1" }, { "title": "90% of new workspaces invite a second person", "weight": 2 } ] } headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.post(url, json=payload, headers=headers) print(response.json()) ``` ```javascript const url = 'https://api.taktoria.com/api/v1/objectives'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"title":"Make onboarding effortless","year":2026,"quarter":3,"keyResults":[{"title":"Median time to first launch under 10 minutes","priority":"P1"},{"title":"90% of new workspaces invite a second person","weight":2}]}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "strings" "net/http" "io" ) func main() { url := "https://api.taktoria.com/api/v1/objectives" payload := strings.NewReader("{\n \"title\": \"Make onboarding effortless\",\n \"year\": 2026,\n \"quarter\": 3,\n \"keyResults\": [\n {\n \"title\": \"Median time to first launch under 10 minutes\",\n \"priority\": \"P1\"\n },\n {\n \"title\": \"90% of new workspaces invite a second person\",\n \"weight\": 2\n }\n ]\n}") req, _ := http.NewRequest("POST", url, payload) req.Header.Add("Authorization", "Bearer ") req.Header.Add("Content-Type", "application/json") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.taktoria.com/api/v1/objectives") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Post.new(url) request["Authorization"] = 'Bearer ' request["Content-Type"] = 'application/json' request.body = "{\n \"title\": \"Make onboarding effortless\",\n \"year\": 2026,\n \"quarter\": 3,\n \"keyResults\": [\n {\n \"title\": \"Median time to first launch under 10 minutes\",\n \"priority\": \"P1\"\n },\n {\n \"title\": \"90% of new workspaces invite a second person\",\n \"weight\": 2\n }\n ]\n}" response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.post("https://api.taktoria.com/api/v1/objectives") .header("Authorization", "Bearer ") .header("Content-Type", "application/json") .body("{\n \"title\": \"Make onboarding effortless\",\n \"year\": 2026,\n \"quarter\": 3,\n \"keyResults\": [\n {\n \"title\": \"Median time to first launch under 10 minutes\",\n \"priority\": \"P1\"\n },\n {\n \"title\": \"90% of new workspaces invite a second person\",\n \"weight\": 2\n }\n ]\n}") .asString(); ``` ```php request('POST', 'https://api.taktoria.com/api/v1/objectives', [ 'body' => '{ "title": "Make onboarding effortless", "year": 2026, "quarter": 3, "keyResults": [ { "title": "Median time to first launch under 10 minutes", "priority": "P1" }, { "title": "90% of new workspaces invite a second person", "weight": 2 } ] }', 'headers' => [ 'Authorization' => 'Bearer ', 'Content-Type' => 'application/json', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.taktoria.com/api/v1/objectives"); var request = new RestRequest(Method.POST); request.AddHeader("Authorization", "Bearer "); request.AddHeader("Content-Type", "application/json"); request.AddParameter("application/json", "{\n \"title\": \"Make onboarding effortless\",\n \"year\": 2026,\n \"quarter\": 3,\n \"keyResults\": [\n {\n \"title\": \"Median time to first launch under 10 minutes\",\n \"priority\": \"P1\"\n },\n {\n \"title\": \"90% of new workspaces invite a second person\",\n \"weight\": 2\n }\n ]\n}", ParameterType.RequestBody); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = [ "Authorization": "Bearer ", "Content-Type": "application/json" ] let parameters = [ "title": "Make onboarding effortless", "year": 2026, "quarter": 3, "keyResults": [ [ "title": "Median time to first launch under 10 minutes", "priority": "P1" ], [ "title": "90% of new workspaces invite a second person", "weight": 2 ] ] ] as [String : Any] let postData = JSONSerialization.data(withJSONObject: parameters, options: []) let request = NSMutableURLRequest(url: NSURL(string: "https://api.taktoria.com/api/v1/objectives")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "POST" request.allHTTPHeaderFields = headers request.httpBody = postData as Data let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```