Tags

https://focus.toggl.com/api/workspaces/{workspace_id}/tags

Returns a list of tags based on the workspace ID. With include_usage, each tag carries usage counts of the projects, tasks and time entries directly tagged with it; usage is omitted for callers whose project access is restricted.

curl  https://focus.toggl.com/api/workspaces/{workspace_id}/tags \
  -H "Content-Type: application/json" \
  -u <email>:<password>

req, err := http.NewRequest(http.MethodGet, 
  "https://focus.toggl.com/api/workspaces/{workspace_id}/tags")
if err != nil {
    print(err)
}
req.Header.Set("Content-Type", "application/json; charset=utf-8")
req.SetBasicAuth("<email>", "<password>")

client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
    print(err)
}

defer resp.Body.Close()
body, err := ioutil.ReadAll(resp.Body)
if err != nil {
    print(err)
}

fmt.Print(string(body))

require 'net/http'
require 'uri'
require 'json'

uri = URI('https://focus.toggl.com/api/workspaces/{workspace_id}/tags')
req = Net::HTTP::Get.new(uri)
req['Content-Type'] = "application/json"
req.basic_auth '<email>', '<password>'
res = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == 'https') do |http|
  http.request(req)
end
puts JSON.parse(res.body)

fetch("https://focus.toggl.com/api/workspaces/{workspace_id}/tags", {
  method: "GET",
  headers: {
	"Content-Type": "application/json",
	"Authorization": `Basic ${base64.encode(<email>:<password>)}`
  },
})
.then((resp) => resp.json())
.then((json) => {
  console.log(json);
})
.catch(err => console.error(err));

import requests
from base64 import b64encode

data = requests.get('https://focus.toggl.com/api/workspaces/{workspace_id}/tags', headers={'content-type': 'application/json', 'Authorization' : 'Basic %s' %  b64encode(b"<email>:<password>").decode("ascii")})
print(data.json())

extern crate tokio;
extern crate serde_json;
use reqwest::{Client};
use reqwest::header::{CONTENT_TYPE};

#[tokio::main]
async fn main() -> Result<(), reqwest::Error> {
  let client = Client::new().basic_auth("<email>", "<password>");
  let json = client.request(Method::GET, "https://focus.toggl.com/api/workspaces/{workspace_id}/tags".to_string())
  .header(CONTENT_TYPE, "application/json")
  .send()
  .await?
  .json()
  .await?;
  
  println!("{:#?}", json);

  Ok(())
}

Parameters

Path

name	type	required	description
workspace_id	integer	true	workspace ID

Query

name	type	required	description
name	string	false	filter by name
page	integer	false	page number
per_page	integer	false	results per page
order_by	[]string	false	order by
tag_id	[]integer	false	filter by tag IDs
include_usage	boolean	false	hydrate per-tag usage counts (settings surface only; adds a warehouse read)
include_archived	boolean	false	list archived tags alongside active ones; an explicit archived param still wins
archived	boolean	false	filter by archived state (true = archived only, false = active only, omit = active only, empty = all tags). Omitting it alongside tag_id returns those ids whatever their state, so an archived tag still attached to an entity resolves.

Response

200

Name	Type	Description
data	Array of object	-
page	integer	-
per_page	integer	-
total	integer	-

data

Name	Type	Description
archived_at	string	An archived tag disappears from the apply affordance but stays attached to and readable on every existing entity. Nothing cascades.
color	string	-
created_at	string	-
deleted_at	string	-
id	integer	-
name	string	-
updated_at	string	-
usage	object	Counts of the projects, tasks and time entries whose tag set directly contains this tag. Only present on the tags list, for callers with unrestricted project access.
workspace_id	integer	-

usage

Name	Type	Description
projects	integer	-
tasks	integer	-
time_entries	integer	-

400

Invalid request

500

Internal Server Error

POST Create a new tag

https://focus.toggl.com/api/workspaces/{workspace_id}/tags

Creates a new tag with the provided details.

curl -X POST https://focus.toggl.com/api/workspaces/{workspace_id}/tags \
  -H "Content-Type: application/json" \
  -d '\{"color":"string","name":"string"\}' \
  -u <email>:<password>

bytes, err := json.Marshal('\{"color":"string","name":"string"\}')
if err != nil {
    print(err)
}
req, err := http.NewRequest(http.MethodPost, 
  "https://focus.toggl.com/api/workspaces/{workspace_id}/tags", bytes.NewBuffer(bytes))
if err != nil {
    print(err)
}
req.Header.Set("Content-Type", "application/json; charset=utf-8")
req.SetBasicAuth("<email>", "<password>")

client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
    print(err)
}

defer resp.Body.Close()
body, err := ioutil.ReadAll(resp.Body)
if err != nil {
    print(err)
}

fmt.Print(string(body))

require 'net/http'
require 'uri'
require 'json'

uri = URI('https://focus.toggl.com/api/workspaces/{workspace_id}/tags')
req = Net::HTTP::Post.new(uri)
req['Content-Type'] = "application/json"
req.body = \{"color":"string","name":"string"\}.to_json
req.basic_auth '<email>', '<password>'
res = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == 'https') do |http|
  http.request(req)
end
puts JSON.parse(res.body)

fetch("https://focus.toggl.com/api/workspaces/{workspace_id}/tags", {
  method: "POST",
  body: \{"color":"string","name":"string"\},
  headers: {
	"Content-Type": "application/json",
	"Authorization": `Basic ${base64.encode(<email>:<password>)}`
  },
})
.then((resp) => resp.json())
.then((json) => {
  console.log(json);
})
.catch(err => console.error(err));

import requests
from base64 import b64encode

data = requests.post('https://focus.toggl.com/api/workspaces/{workspace_id}/tags', json=\{"color":"string","name":"string"\}, headers={'content-type': 'application/json', 'Authorization' : 'Basic %s' %  b64encode(b"<email>:<password>").decode("ascii")})
print(data.json())

extern crate tokio;
extern crate serde_json;
use reqwest::{Client};
use reqwest::header::{CONTENT_TYPE};

#[tokio::main]
async fn main() -> Result<(), reqwest::Error> {
  let client = Client::new().basic_auth("<email>", "<password>");
  let json = client.request(Method::POST, "https://focus.toggl.com/api/workspaces/{workspace_id}/tags".to_string())
.json(&serde_json::json!(\{"color":"string","name":"string"\}))
  .header(CONTENT_TYPE, "application/json")
  .send()
  .await?
  .json()
  .await?;
  
  println!("{:#?}", json);

  Ok(())
}

Parameters

Path

name	type	required	description
workspace_id	integer	true	workspace ID

Body

Name	Type	Description
color	string	-
name	string	-

Response

201

Tag created successfully

400

Invalid request

500

Internal Server Error

GET Get tag by ID

https://focus.toggl.com/api/workspaces/{workspace_id}/tags/{tag_id}

Returns a tag with the provided ID.

curl  https://focus.toggl.com/api/workspaces/{workspace_id}/tags/{tag_id} \
  -H "Content-Type: application/json" \
  -u <email>:<password>

req, err := http.NewRequest(http.MethodGet, 
  "https://focus.toggl.com/api/workspaces/{workspace_id}/tags/{tag_id}")
if err != nil {
    print(err)
}
req.Header.Set("Content-Type", "application/json; charset=utf-8")
req.SetBasicAuth("<email>", "<password>")

client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
    print(err)
}

defer resp.Body.Close()
body, err := ioutil.ReadAll(resp.Body)
if err != nil {
    print(err)
}

fmt.Print(string(body))

require 'net/http'
require 'uri'
require 'json'

uri = URI('https://focus.toggl.com/api/workspaces/{workspace_id}/tags/{tag_id}')
req = Net::HTTP::Get.new(uri)
req['Content-Type'] = "application/json"
req.basic_auth '<email>', '<password>'
res = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == 'https') do |http|
  http.request(req)
end
puts JSON.parse(res.body)

fetch("https://focus.toggl.com/api/workspaces/{workspace_id}/tags/{tag_id}", {
  method: "GET",
  headers: {
	"Content-Type": "application/json",
	"Authorization": `Basic ${base64.encode(<email>:<password>)}`
  },
})
.then((resp) => resp.json())
.then((json) => {
  console.log(json);
})
.catch(err => console.error(err));

import requests
from base64 import b64encode

data = requests.get('https://focus.toggl.com/api/workspaces/{workspace_id}/tags/{tag_id}', headers={'content-type': 'application/json', 'Authorization' : 'Basic %s' %  b64encode(b"<email>:<password>").decode("ascii")})
print(data.json())

extern crate tokio;
extern crate serde_json;
use reqwest::{Client};
use reqwest::header::{CONTENT_TYPE};

#[tokio::main]
async fn main() -> Result<(), reqwest::Error> {
  let client = Client::new().basic_auth("<email>", "<password>");
  let json = client.request(Method::GET, "https://focus.toggl.com/api/workspaces/{workspace_id}/tags/{tag_id}".to_string())
  .header(CONTENT_TYPE, "application/json")
  .send()
  .await?
  .json()
  .await?;
  
  println!("{:#?}", json);

  Ok(())
}

Parameters

Path

name	type	required	description
workspace_id	integer	true	workspace ID
tag_id	integer	true	tag ID

Response

200

Name	Type	Description
archived_at	string	An archived tag disappears from the apply affordance but stays attached to and readable on every existing entity. Nothing cascades.
color	string	-
created_at	string	-
deleted_at	string	-
id	integer	-
name	string	-
updated_at	string	-
usage	object	Counts of the projects, tasks and time entries whose tag set directly contains this tag. Only present on the tags list, for callers with unrestricted project access.
workspace_id	integer	-

usage

Name	Type	Description
projects	integer	-
tasks	integer	-
time_entries	integer	-

400

Invalid request

500

Internal Server Error

PUT Update tag

https://focus.toggl.com/api/workspaces/{workspace_id}/tags/{tag_id}

Update an existing tag

curl -X PUT https://focus.toggl.com/api/workspaces/{workspace_id}/tags/{tag_id} \
  -H "Content-Type: application/json" \
  -d '\{"color":"string","name":"string"\}'

bytes, err := json.Marshal('\{"color":"string","name":"string"\}')
if err != nil {
    print(err)
}
req, err := http.NewRequest(http.MethodPut, 
  "https://focus.toggl.com/api/workspaces/{workspace_id}/tags/{tag_id}", bytes.NewBuffer(bytes))
if err != nil {
    print(err)
}
req.Header.Set("Content-Type", "application/json; charset=utf-8")

client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
    print(err)
}

defer resp.Body.Close()
body, err := ioutil.ReadAll(resp.Body)
if err != nil {
    print(err)
}

fmt.Print(string(body))

require 'net/http'
require 'uri'
require 'json'

uri = URI('https://focus.toggl.com/api/workspaces/{workspace_id}/tags/{tag_id}')
req = Net::HTTP::Put.new(uri)
req['Content-Type'] = "application/json"
req.body = \{"color":"string","name":"string"\}.to_json
res = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == 'https') do |http|
  http.request(req)
end
puts JSON.parse(res.body)

fetch("https://focus.toggl.com/api/workspaces/{workspace_id}/tags/{tag_id}", {
  method: "PUT",
  body: \{"color":"string","name":"string"\},
  headers: {
	"Content-Type": "application/json"
  },
})
.then((resp) => resp.json())
.then((json) => {
  console.log(json);
})
.catch(err => console.error(err));

import requests
from base64 import b64encode

data = requests.put('https://focus.toggl.com/api/workspaces/{workspace_id}/tags/{tag_id}', json=\{"color":"string","name":"string"\}, headers={'content-type': 'application/json'})
print(data.json())

extern crate tokio;
extern crate serde_json;
use reqwest::{Client};
use reqwest::header::{CONTENT_TYPE};

#[tokio::main]
async fn main() -> Result<(), reqwest::Error> {
  let client = Client::new();
  let json = client.request(Method::PUT, "https://focus.toggl.com/api/workspaces/{workspace_id}/tags/{tag_id}".to_string())
.json(&serde_json::json!(\{"color":"string","name":"string"\}))
  .header(CONTENT_TYPE, "application/json")
  .send()
  .await?
  .json()
  .await?;
  
  println!("{:#?}", json);

  Ok(())
}

Parameters

Path

name	type	required	description
workspace_id	integer	true	workspace ID
tag_id	integer	true	Tag ID

Body

Name	Type	Description
color	string	-
name	string	-

Response

200

Successfully updated tag

Name	Type	Description
archived_at	string	An archived tag disappears from the apply affordance but stays attached to and readable on every existing entity. Nothing cascades.
color	string	-
created_at	string	-
deleted_at	string	-
id	integer	-
name	string	-
updated_at	string	-
usage	object	Counts of the projects, tasks and time entries whose tag set directly contains this tag. Only present on the tags list, for callers with unrestricted project access.
workspace_id	integer	-

usage

Name	Type	Description
projects	integer	-
tasks	integer	-
time_entries	integer	-

400

Invalid request

500

Internal Server Error

DELETE Delete a tag by ID

https://focus.toggl.com/api/workspaces/{workspace_id}/tags/{tag_id}

Deletes a tag with the provided ID.

curl -X DELETE https://focus.toggl.com/api/workspaces/{workspace_id}/tags/{tag_id} \
  -H "Content-Type: application/json" \
  -u <email>:<password>

req, err := http.NewRequest(http.MethodPut, 
  "https://focus.toggl.com/api/workspaces/{workspace_id}/tags/{tag_id}")
if err != nil {
    print(err)
}
req.Header.Set("Content-Type", "application/json; charset=utf-8")
req.SetBasicAuth("<email>", "<password>")

client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
    print(err)
}

defer resp.Body.Close()
body, err := ioutil.ReadAll(resp.Body)
if err != nil {
    print(err)
}

fmt.Print(string(body))

require 'net/http'
require 'uri'
require 'json'

uri = URI('https://focus.toggl.com/api/workspaces/{workspace_id}/tags/{tag_id}')
req = Net::HTTP::Delete.new(uri)
req['Content-Type'] = "application/json"
req.basic_auth '<email>', '<password>'
res = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == 'https') do |http|
  http.request(req)
end
puts JSON.parse(res.body)

fetch("https://focus.toggl.com/api/workspaces/{workspace_id}/tags/{tag_id}", {
  method: "DELETE",
  headers: {
	"Content-Type": "application/json",
	"Authorization": `Basic ${base64.encode(<email>:<password>)}`
  },
})
.then((resp) => resp.json())
.then((json) => {
  console.log(json);
})
.catch(err => console.error(err));

import requests
from base64 import b64encode

data = requests.delete('https://focus.toggl.com/api/workspaces/{workspace_id}/tags/{tag_id}', headers={'content-type': 'application/json', 'Authorization' : 'Basic %s' %  b64encode(b"<email>:<password>").decode("ascii")})
print(data.json())

extern crate tokio;
extern crate serde_json;
use reqwest::{Client};
use reqwest::header::{CONTENT_TYPE};

#[tokio::main]
async fn main() -> Result<(), reqwest::Error> {
  let client = Client::new().basic_auth("<email>", "<password>");
  let json = client.request(Method::DELETE, "https://focus.toggl.com/api/workspaces/{workspace_id}/tags/{tag_id}".to_string())
  .header(CONTENT_TYPE, "application/json")
  .send()
  .await?
  .json()
  .await?;
  
  println!("{:#?}", json);

  Ok(())
}

Parameters

Path

name	type	required	description
workspace_id	integer	true	workspace ID
tag_id	integer	true	tag ID

Response

204

Successfully deleted tag

400

Invalid request

500

Internal Server Error

PATCH Restore a tag by ID

https://focus.toggl.com/api/workspaces/{workspace_id}/tags/{tag_id}/restore

Restores a tag by the provided ID.

curl -X PATCH https://focus.toggl.com/api/workspaces/{workspace_id}/tags/{tag_id}/restore \
  -H "Content-Type: application/json" \
  -u <email>:<password>

req, err := http.NewRequest(http.MethodGet, 
  "https://focus.toggl.com/api/workspaces/{workspace_id}/tags/{tag_id}/restore")
if err != nil {
    print(err)
}
req.Header.Set("Content-Type", "application/json; charset=utf-8")
req.SetBasicAuth("<email>", "<password>")

client := &http.Client{}
resp, err := client.Do(req)
if err != nil {
    print(err)
}

defer resp.Body.Close()
body, err := ioutil.ReadAll(resp.Body)
if err != nil {
    print(err)
}

fmt.Print(string(body))

require 'net/http'
require 'uri'
require 'json'

uri = URI('https://focus.toggl.com/api/workspaces/{workspace_id}/tags/{tag_id}/restore')
req = Net::HTTP::Patch.new(uri)
req['Content-Type'] = "application/json"
req.basic_auth '<email>', '<password>'
res = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == 'https') do |http|
  http.request(req)
end
puts JSON.parse(res.body)

fetch("https://focus.toggl.com/api/workspaces/{workspace_id}/tags/{tag_id}/restore", {
  method: "PATCH",
  headers: {
	"Content-Type": "application/json",
	"Authorization": `Basic ${base64.encode(<email>:<password>)}`
  },
})
.then((resp) => resp.json())
.then((json) => {
  console.log(json);
})
.catch(err => console.error(err));

import requests
from base64 import b64encode

data = requests.patch('https://focus.toggl.com/api/workspaces/{workspace_id}/tags/{tag_id}/restore', headers={'content-type': 'application/json', 'Authorization' : 'Basic %s' %  b64encode(b"<email>:<password>").decode("ascii")})
print(data.json())

extern crate tokio;
extern crate serde_json;
use reqwest::{Client};
use reqwest::header::{CONTENT_TYPE};

#[tokio::main]
async fn main() -> Result<(), reqwest::Error> {
  let client = Client::new().basic_auth("<email>", "<password>");
  let json = client.request(Method::PATCH, "https://focus.toggl.com/api/workspaces/{workspace_id}/tags/{tag_id}/restore".to_string())
  .header(CONTENT_TYPE, "application/json")
  .send()
  .await?
  .json()
  .await?;
  
  println!("{:#?}", json);

  Ok(())
}

Parameters

Path

name	type	required	description
workspace_id	integer	true	workspace ID
tag_id	integer	true	tag ID

Response

204

Successfully restored tag

400

Invalid request

409

Another tag already holds this integration identity

500

Internal Server Error

GET List tags​

Parameters​

Path​

Query​

Response​

200​

data​

usage​

400​

500​

POST Create a new tag​

Parameters​

Path​

Body​

Response​

201​

400​

500​

GET Get tag by ID​

Parameters​

Path​

Response​

200​

usage​

400​

500​

PUT Update tag​

Parameters​

Path​

Body​

Response​

200​

usage​

400​

500​

DELETE Delete a tag by ID​

Parameters​

Path​

Response​

204​

400​

500​

PATCH Restore a tag by ID​

Parameters​

Path​

Response​

204​

400​

409​

500​

GET List tags

Parameters

Path

Query

Response

200

data

usage

400

500

POST Create a new tag

Parameters

Path

Body

Response

201

400

500

GET Get tag by ID

Parameters

Path

Response

200

usage

400

500

PUT Update tag

Parameters

Path

Body

Response

200

usage

400

500

DELETE Delete a tag by ID

Parameters

Path

Response

204

400

500

PATCH Restore a tag by ID

Parameters

Path

Response

204

400

409

500