Skip to main content
Use POST /v1/subjects to create a new subject profile. Choose a type — study, training, or inactive — which determines what content the subject tracks and how its blocks appear in the app.

​
Endpoint

POST https://api.taketime.app/v1/subjects

​
Body Parameters

​
name
string
required
Display name for the subject. Maximum 40 characters. Must be unique across your account — the API returns a VALIDATION_ERROR if the name is already in use.
​
type
string
required
The subject type. Must be one of study, training, or inactive. This determines what content fields are available and cannot be changed after creation.
​
color
string
A hex color code to represent this subject in the app (e.g. #6366f1). If omitted, a color is assigned automatically.
​
slots
array
An array of weekly time slot objects. Each slot defines when this subject is regularly scheduled. If omitted, the subject is created with no scheduled slots.Each slot object has the following shape:
{
  "days": [1, 3, 5],
  "start": "09:00",
  "end": "10:00"
}
  • days — array of integers representing days of the week
  • start — slot start time in HH:MM format
  • end — slot end time in HH:MM format; must be after start

​
Response

Returns the newly created subject object inside the data field with HTTP status 201 Created.
​
id
string
Unique identifier for the newly created subject.
​
name
string
Display name of the subject.
​
type
string
The subject type: study, training, or inactive.
​
color
string
Hex color code assigned to this subject.
​
slots
array
The weekly time slots configured for this subject. Empty array if none were provided.
​
syllabus
array
Array of syllabus topic objects. Empty on creation. Each item has title (string), duration (integer, minutes), and done (boolean).
Example response 
{
  "data": {
    "id": "sub_xyz",
    "name": "JavaScript",
    "type": "study",
    "color": "#6366f1",
    "slots": [
      {
        "days": [1, 3, 5],
        "start": "09:00",
        "end": "10:00"
      }
    ],
    "syllabus": []
  },
  "error": null,
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-06-11T09:00:00Z"
  }
}

​
Examples

curl -X POST https://api.taketime.app/v1/subjects \
  -H "Authorization: Bearer tt_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "JavaScript",
    "type": "study",
    "color": "#6366f1",
    "slots": [
      {
        "days": [1, 3, 5],
        "start": "09:00",
        "end": "10:00"
      }
    ]
  }'
After creating a subject, use the List Blocks or Create Block endpoints to start scheduling study sessions for it.