1. Overview
| Item | Value |
|---|---|
| Base URL (on-premise) | https://<your-domain>/serv/api/external/v1 |
| Protocol | HTTPS · GET only · JSON (UTF-8) |
| Auth | API key (X-API-Key header or Authorization: Bearer) |
| Data scope | Only the one workspace the key was issued for |
| Rate limit | 60 requests per minute per key by default |
The path includes /serv. Without it you get the website's 404 page instead of the API.
There are five endpoints.
| Method | Path | Required scope | Description |
|---|---|---|---|
| GET | /health | None (no key) | Service status |
| GET | /members | members:read | Workspace members (guests excluded) |
| GET | /spaces | spaces:read | Spaces (departments, rooms) |
| GET | /spaces/{id} | spaces:read | A single space |
| GET | /attendances | attendances:read | Attendance records for a period |
2. First calls
① Check status (no key)
curl -s https://<your-domain>/serv/api/external/v1/health{"success":true,"data":{"status":"UP","time":"2026-10-19T14:43:46.414+09:00","build":"unknown"}}② List members (key required)
curl -s -H "X-API-Key: $JC_API_KEY" \
"https://<your-domain>/serv/api/external/v1/members?limit=50"③ Attendance (period required)
curl -s -H "X-API-Key: $JC_API_KEY" \
"https://<your-domain>/serv/api/external/v1/attendances?from=2026-10-01&to=2026-10-31"Put your issued key (it starts with jc_) in $JC_API_KEY. Never leave keys in code, repositories or chat.
3. Authentication
Send the key in one of two ways. If both are present, X-API-Key wins.
X-API-Key: jc_xxxxxxxxxxxxxxxxAuthorization: Bearer jc_xxxxxxxxxxxxxxxx- Keys always start with
jc_. ABearervalue that does not start withjc_is treated as no key and returns401. - The key is shown in full only once, when issued. The server stores only an irreversible hash, so a lost key must be reissued.
- Missing, unknown, revoked or expired keys and suspended contracts all return the same
401(JC-4001). We deliberately do not say which. /healthalso returns401if you attach a wrong key. Without a key it returns 200.- A key's workspace cannot be changed, and there is no parameter for a workspace ID.
4. Scopes
Each key can call only the endpoints its scopes allow. A missing scope returns 403 (JC-4003) and the message names the required scope.
| scope | Endpoints |
|---|---|
members:read | GET /members |
spaces:read | GET /spaces · GET /spaces/{id} |
attendances:read | GET /attendances |
Request only the scopes you need (least privilege). Adding scopes may require reissuing the key.
5. Response format
Success
{
"success": true,
"data": [ ],
"meta": { "cursor": "bzo1MA", "hasMore": true }
}- List endpoints (
members,spaces,attendances) return an array indataplusmeta. - The single-item endpoint (
spaces/{id}) andhealthhave nometa. - Empty fields are omitted, not sent as
null. Treat a missing key as "no value". - Fields may be added later. Ignore fields you don't know.
Failure
{
"success": false,
"error": { "code": "JC-4001", "message": "유효한 API 키가 필요합니다." }
}- Branch on
error.code.error.messageis human-readable text in Korean and its wording may change. error.detailappears only when present (mainly missing or malformed parameters). Failures carry nodataormeta.- See 10. Error codes for the full list.
6. Pagination
- Lists are paged with
limit(items per page) andcursor(next-page marker). limitdefaults to 50, max 200. Values above 200 become 200 and values below 1 become 1 (not an error). Non-numeric values return400.- If
meta.hasMoreistrue, passmeta.cursorunchanged as?cursor=on the next request. When it isfalseyou are on the last page and there is nocursor. cursoris an opaque string. Do not parse or build it. A malformed cursor returns400.- Ordering is fixed:
membersby nickname (thenmemberSeq),spacesbyspaceSeq,attendancesbyattendanceSeq. Data changing between pages can cause overlaps or gaps, so for a full sync read to the end and de-duplicate by ID.
URL="https://<your-domain>/serv/api/external/v1/members?limit=200"
CURSOR=""
while : ; do
RES=$(curl -s -H "X-API-Key: $JC_API_KEY" "$URL${CURSOR:+&cursor=$CURSOR}")
echo "$RES" | jq -c '.data[]'
[ "$(echo "$RES" | jq -r '.meta.hasMore')" = "true" ] || break
CURSOR=$(echo "$RES" | jq -r '.meta.cursor')
done7. Rate limits
- The limit is requests per minute per API key. The default is 60/min and may differ per key.
- Counting uses fixed one-minute windows (reset when the clock minute changes). Every authenticated request counts, whatever its result. Requests rejected before authentication and keyless
healthcalls do not count. - Over the limit you get
429+JC-4029with the headerRetry-After: 60. The value is always 60, not the seconds remaining. - On 429, wait for
Retry-After; for other retries use exponential backoff.
HTTP/1.1 429
Retry-After: 60
{"success":false,"error":{"code":"JC-4029","message":"분당 요청 한도(60)를 초과했습니다."}}8. Dates and times
- Date parameters use
yyyy-MM-ddand are read as days in Korea Standard Time (KST, UTC+9). - Response timestamps are ISO-8601 and always carry
+09:00, e.g.2026-10-19T09:01:00+09:00. Milliseconds may appear, so use an ISO-8601 parser rather than fixed-width slicing.
9. Endpoints
/health
No keyService status. A wrong key returns 401.
| Field | Type | Description |
|---|---|---|
status | string | "UP" when healthy |
time | string (ISO-8601) | Current server time (KST) |
build | string | Identifier of the running build, or "unknown". The format is not guaranteed; use it for display and logs only |
/members
members:readWorkspace members, ordered by nickname. Guests and members who have left are excluded.
| Parameter | In | Required | Description |
|---|---|---|---|
limit | query | No | 1–200, default 50 |
cursor | query | No | meta.cursor from the previous response |
| Field | Type | Description |
|---|---|---|
memberSeq | integer | Member ID (unique within the workspace). Same value as memberSeq in attendance |
account | string | Login account (email format). Use it to match employees in your system |
name | string | Name |
nickname | string | Display name in the workspace |
jobGrade | string | Job grade (omitted if none) |
spaceName | string | Space (department) name (omitted if none) |
status | string | Current status name as set in the workspace, in Korean (e.g. 온라인 online, 오프라인 offline, 부재중 away). New values may appear; accept unknown ones as-is |
Phone numbers, addresses, location, birth dates and business details are not provided.
curl -s -H "X-API-Key: $JC_API_KEY" \
"https://<your-domain>/serv/api/external/v1/members?limit=2"{
"success": true,
"data": [
{ "memberSeq": 1021, "account": "alex.kim@example.com", "name": "Alex Kim",
"nickname": "Alex", "jobGrade": "Manager", "spaceName": "Engineering", "status": "온라인" },
{ "memberSeq": 1034, "account": "jamie.lee@example.com", "name": "Jamie Lee",
"nickname": "Jamie", "status": "오프라인" }
],
"meta": { "cursor": "bzoy", "hasMore": true }
}/spaces
spaces:readActive spaces (departments, rooms), ordered by spaceSeq. Parameters: limit, cursor (as above).
| Field | Type | Description |
|---|---|---|
spaceSeq | integer | Space ID |
name | string | Space name |
topSpaceSeq | integer | Parent space ID. Omitted for top-level spaces |
{
"success": true,
"data": [
{ "spaceSeq": 301, "name": "Head office" },
{ "spaceSeq": 305, "name": "Engineering", "topSpaceSeq": 301 }
],
"meta": { "hasMore": false }
}/spaces/{id}
spaces:readA single space. A non-integer id (path) returns 400. data has the same shape as a list item above.
curl -s -H "X-API-Key: $JC_API_KEY" "https://<your-domain>/serv/api/external/v1/spaces/305"{ "success": true, "data": { "spaceSeq": 305, "name": "Engineering", "topSpaceSeq": 301 } }Missing spaces, deleted spaces and spaces in another workspace all return the same 404 (JC-4004), so nobody can probe for other organizations' data.
/attendances
attendances:readAttendance records with a clock-in within the period.
| Parameter | In | Required | Description |
|---|---|---|---|
from | query | Yes | Start date yyyy-MM-dd (KST, from 00:00) |
to | query | Yes | End date yyyy-MM-dd (KST, through end of day) |
memberSeq | query | No | Only this member. Unknown IDs return an empty list |
limit | query | No | 1–200, default 50 |
cursor | query | No | meta.cursor from the previous response |
fromandtoare both required. Missing or malformed values, ortobeforefrom, return400.- The period can be at most 92 days, both ends included (e.g. 2026-07-01 to 2026-09-30). Split longer ranges.
- Filtering uses the originally recorded clock-in. A record whose clock-in was corrected by an admin still appears if the original day is in range, and
clockIncarries the corrected value.
| Field | Type | Description |
|---|---|---|
attendanceSeq | integer | Attendance record ID |
memberSeq | integer | Member ID |
memberName | string | Member nickname |
clockIn | string (ISO-8601) | Clock-in time; the admin-corrected value if any |
clockOut | string (ISO-8601) | Clock-out time. Omitted if not clocked out yet |
outside | string (HH:mm) | Time spent in "out of office" status that day. "00:00" if none |
missed | string (HH:mm) | Time spent in "away" status that day. "00:00" if none |
Attendance notes are not provided because they may contain personal information. Today's outside and missed count up to now, so they can grow on later reads.
curl -s -H "X-API-Key: $JC_API_KEY" \
"https://<your-domain>/serv/api/external/v1/attendances?from=2026-10-19&to=2026-10-19&memberSeq=1021"{
"success": true,
"data": [
{ "attendanceSeq": 88123, "memberSeq": 1021, "memberName": "Alex",
"clockIn": "2026-10-19T08:57:12+09:00", "clockOut": "2026-10-19T18:03:40+09:00",
"outside": "01:20", "missed": "00:00" }
],
"meta": { "hasMore": false }
}{ "success": false, "error": { "code": "JC-4000", "message": "조회 기간은 최대 92일까지 가능합니다." } }
{ "success": false, "error": { "code": "JC-4000",
"message": "요청 파라미터가 올바르지 않습니다.", "detail": "'from' 칸이 필요합니다." } }10. Error codes
| Code | HTTP | Meaning | Typical cause | Retry? |
|---|---|---|---|---|
JC-4000 | 400 | Bad request | Attendance from/to missing, malformed or over 92 days; unreadable cursor; non-numeric number fields | Fix the request |
JC-4001 | 401 | Authentication failed | Missing, unknown, revoked or expired key; suspended contract; wrong key on health | Check or reissue the key |
JC-4003 | 403 | Insufficient scope | The key lacks the endpoint's scope (message names it) | Request the scope |
JC-4004 | 404 | Not found | Missing or deleted space, or a space in another workspace | Check the ID |
JC-4029 | 429 | Rate limit exceeded | Per-key per-minute limit exceeded · Retry-After: 60 | After 60 seconds |
JC-5000 | 500 | Internal server error | Unexpected error (generic message only) | Retry later; contact us if it persists |
- 401 never says why, and 403 means a missing scope only. Another workspace's data returns 404, not 403.
- 4xxx codes are caller-side, 5xxx server-side. If you get a code not listed here, handle it by HTTP status and let us know.
- Rejections by front-end infrastructure (firewall, CDN: 502, 503, 504 …) and undefined paths may not use this format. If the body is not JSON, check the URL first.
11. Receiving webhooks
teamside can send work notifications to a URL you choose. Unlike the read API above, this section is for building the receiving side.
Setup
- Workspace owners and admins register receiving URLs in the settings screen (up to 20 per workspace). API keys cannot register them.
- For each URL you choose the notification types (or "all"), the scope (whole workspace / specific projects / specific approval forms) and whether to hide titles. With hidden titles, titles are removed from the body entirely.
- URLs must be reachable from the internet. Private network addresses are rejected at registration and checked again before sending. Redirects (3xx) are not followed, so register the final URL.
- Sending must be enabled by the server operator. Confirm it is on when you start.
Delivery
POST·Content-Type: application/json· UTF-8 JSON body.- Reply with
2xxwithin 3 s to connect and 10 s to respond. Do slow work after acknowledging. - URLs with a signing secret receive
X-JC-Signature: sha256=<lowercase hex>. - They also receive
X-JC-Signature-V2: t=<unix seconds>,v1=<lowercase hex>, which includes the send time (since 2026-11-08). Check it to reject replayed requests. - Because of retries, the same body can arrive more than once. De-duplicate by
eventandalarmSeq(oroccurredAt+subject).
Signature verification
The signature is HMAC-SHA256 over the raw body bytes as received (not re-serialized), keyed with your signing secret. Compare in constant time.
const crypto = require('crypto');
function verify(rawBody, header, secret) {
const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(rawBody, 'utf8').digest('hex');
const a = Buffer.from(expected), b = Buffer.from(header || '');
return a.length === b.length && crypto.timingSafeEqual(a, b);
}import hmac, hashlib
def verify(raw_body: bytes, header: str, secret: str) -> bool:
expected = 'sha256=' + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, header or '')Verifying the timestamped signature (V2)
v1 is HMAC-SHA256 over t + . + the raw request body. Reject it if t is more than 5 minutes from now. Retries are re-signed with the retry time. X-JC-Signature is still sent, so existing verification keeps working.
const crypto = require('crypto');
// header e.g. "t=1700000000,v1=2f65…" · reject anything older than 5 minutes (300 s)
function verifyV2(rawBody, header, secret, nowSec = Math.floor(Date.now() / 1000)) {
const m = /^t=(\d+),v1=([0-9a-f]{64})$/.exec(header || '');
if (!m || Math.abs(nowSec - Number(m[1])) > 300) return false;
const expected = crypto.createHmac('sha256', secret).update(m[1] + '.' + rawBody, 'utf8').digest('hex');
return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(m[2]));
}Body (plain JSON URLs)
{
"event": "approval.requested",
"occurredAt": 1792382400000,
"workspaceSeq": 12,
"alarmSeq": 55012,
"actor": "Alex",
"recipients": [1034, 1050],
"subject": { "requestSeq": 7001, "title": "October travel expenses", "requestType": "Expense report" }
}| Field | Description |
|---|---|
event | Event key (table below). Names never change once published |
occurredAt | Event time as epoch milliseconds (number) |
workspaceSeq | Workspace ID |
alarmSeq | Notification ID (omitted for events without one) |
actor | Display name of whoever triggered the event |
recipients | Member IDs who receive the notification (omitted for events without one) |
subject | Event details. Fields vary by type and may grow. Absent entirely for URLs with hidden titles |
Plain JSON bodies carry no human-readable sentence. Build your own wording from the event key.
Event keys
| Group | Event keys |
|---|---|
| Approvals | approval.requestedapproval.forwardedapproval.referencedapproval.approvedapproval.rejectedapproval.withdrawnapproval.canceledapproval.deletedapproval.commentedapproval.dueapproval.reminded |
| Attendance · leave | attendance.week.warnattendance.week.overvacation.promotion.urgedvacation.promotion.assigned |
| Inquiries · posts · surveys | inquiry.createdboard.postedsurvey.openedsurvey.reopened |
| Meetings · seminars · resources | meeting.scheduledmeeting.canceledmeeting.startedseminar.scheduledseminar.canceledseminar.startedresource.bookedresource.canceled |
| Kanban | task.assignedtask.duetask.completed (only to URLs scoped to projects) |
| Members | member.joined (only to plain JSON URLs set to "all") |
member.joined goes only to plain JSON URLs set to "all", and its occurredAt is a string, not a number. Branch on event first.
Receiving in Teams or Slack
If the URL host is hooks.slack.com, *.webhook.office.com, *.environment.api.powerplatform.com or *.logic.azure.com, teamside sends a one-line notification in that service's format. The plain JSON body and signature are not used.
Failures and retries
| Response | Handling |
|---|---|
2xx | Success |
408 · 429 · 5xx · 3xx · connection failure · timeout | Retry |
Other 4xx | Give up immediately |
Up to 5 attempts in total (1 + 4 retries) with growing intervals (up to about 4 minutes). Deliveries that fail all 5 attempts are not resent. Notifications are not queued while a URL is turned off.
12. AI tools (MCP)
AI tools such as Claude, ChatGPT and Gemini can use teamside as MCP tools with the same API key. No extra server: just one URL.
| Item | Value |
|---|---|
| URL | https://<your-domain>/serv/api/external/v1/mcp |
| Transport | MCP Streamable HTTP · stateless |
| Auth | The API key from section 3 (Authorization: Bearer jc_… or X-API-Key) |
Only read tools within the key's scopes are listed: list_members · list_spaces · get_space · list_attendances. The same rules apply as for REST (cursor, limit, 92 days), and each MCP request counts once toward the rate limit.
claude mcp add --transport http joycollab https://<your-domain>/serv/api/external/v1/mcp \
--header "Authorization: Bearer ${JC_API_KEY}"Member and attendance data read through AI tools is passed to the AI provider you choose. Check your internal privacy rules (member consent, processing agreements) first.
Connection examples for each tool come with the onboarding consultation. MCP is off by default; each company decides whether to turn it on.
13. Getting a key
Workspace owners and admins can create and revoke keys themselves in teamside under Settings › Admin › “Integration keys”. Choose what each key can read (section 4); the full key is shown only once, when created. Up to 10 active keys per workspace.
If you can't create one yourself or need a different rate limit, ask us and include:
- The workspace to connect (name or URL)
- The scopes you need (section 4)
- Expected volume (calls per minute, sync interval)
- Whether you want an expiry date
- Whether it will be used by AI tools (MCP) — if so, confirmation that your privacy rules have been checked
If a key is lost or may have leaked, tell us right away; we will revoke it and issue a new one. For on-premise installations, ask your installation contact.
Need help with scopes or call volume? Just ask.
API key & integration inquiry14. Troubleshooting
| Symptom | Check |
|---|---|
| Website 404 HTML returned | Whether /serv is missing from the URL |
401 | Typos, the jc_ prefix, the space after Bearer, expiry, revocation. Don't attach a wrong key to health |
403 | Request the scope named in the message |
400 on attendance | from/to format, within 92 days, to ≥ from |
404 on a space | Whether the space belongs to this key's workspace |
429 | Per-minute limit exceeded. Retry after 60 seconds |
| Duplicates or gaps | Data changed between pages. See section 6 |
Last updated 2026-11-06 · API v1