Create a tag

Owner/Admin/Editor; active workspace/project required. Current membership is checked again after locks. Trimmed NFC names are 1–50 characters and case-insensitively unique per project.

POST /api/v1/workspaces/{workspaceId}/projects/{projectId}/branches/{branchId}/tags

Operation: createProjectTag · Download OpenAPI

Access

Requires an authenticated Localisync panel session. The API checks current membership and permissions for workspace operations. See authentication and request rules.

sessionCookie

{
  "type": "apiKey",
  "in": "cookie",
  "name": "__Host-localisync-session",
  "description": "Production Secure HttpOnly session. Explicit local HTTP uses localisync-session."
}

Parameters

Name	Location	Required	Description
workspaceId	path	Yes	See constraints below.
projectId	path	Yes	See constraints below.
branchId	path	Yes	See constraints below.
Origin	header	Yes	Must equal the configured panel origin.
X-CSRF-Token	header	Yes	Session-bound token from auth/me.

workspaceId

{
  "type": "string",
  "format": "uuid"
}

projectId

{
  "type": "string",
  "format": "uuid"
}

branchId

{
  "type": "string",
  "format": "uuid"
}

Origin

{
  "type": "string",
  "format": "uri"
}

X-CSRF-Token

{
  "type": "string"
}

Request body

Required: Yes.

application/json

Schema reference: TagCreate.

Field	Type	Required	Constraints / description
name	string	Yes	maxLength: 100

{
  "$ref": "#/components/schemas/TagCreate"
}

Responses

201

Successful response. Queued jobs still require polling; completion is explicit.

Content type: application/json Schema reference: Tag.

Field	Type	Required	Constraints / description
id	string	Yes	format: "uuid"; pattern: "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"
name	string	Yes	—
version	integer	Yes	maximum: 9007199254740991
usageCount	integer	Yes	minimum: 0; maximum: 9007199254740991

{
  "$ref": "#/components/schemas/Tag"
}

400

Invalid mapping, options or content.

Content type: application/json Schema reference: Error.

Field	Type	Required	Constraints / description
error	string	Yes	—
message	string	Yes	—
requestId	string	Yes	—
details	See schema	No	—

{
  "$ref": "#/components/schemas/Error"
}

401

Sign in required.

Content type: application/json Schema reference: Error.

Field	Type	Required	Constraints / description
error	string	Yes	—
message	string	Yes	—
requestId	string	Yes	—
details	See schema	No	—

{
  "$ref": "#/components/schemas/Error"
}

403

Current role cannot perform this operation.

Content type: application/json Schema reference: Error.

Field	Type	Required	Constraints / description
error	string	Yes	—
message	string	Yes	—
requestId	string	Yes	—
details	See schema	No	—

{
  "$ref": "#/components/schemas/Error"
}

404

Resource unavailable in this actor and project scope.

Content type: application/json Schema reference: Error.

Field	Type	Required	Constraints / description
error	string	Yes	—
message	string	Yes	—
requestId	string	Yes	—
details	See schema	No	—

{
  "$ref": "#/components/schemas/Error"
}

409

Stale revision, conflicting idempotency key or invalid job state.

Content type: application/json Schema reference: Error.

Field	Type	Required	Constraints / description
error	string	Yes	—
message	string	Yes	—
requestId	string	Yes	—
details	See schema	No	—

{
  "$ref": "#/components/schemas/Error"
}

413

Upload or body limit exceeded.

Content type: application/json Schema reference: Error.

Field	Type	Required	Constraints / description
error	string	Yes	—
message	string	Yes	—
requestId	string	Yes	—
details	See schema	No	—

{
  "$ref": "#/components/schemas/Error"
}

429

Request rate limit exceeded.

Content type: application/json Schema reference: Error.

Field	Type	Required	Constraints / description
error	string	Yes	—
message	string	Yes	—
requestId	string	Yes	—
details	See schema	No	—

{
  "$ref": "#/components/schemas/Error"
}

503

Dependency unavailable; no success is reported.

Content type: application/json Schema reference: Error.

Field	Type	Required	Constraints / description
error	string	Yes	—
message	string	Yes	—
requestId	string	Yes	—
details	See schema	No	—

{
  "$ref": "#/components/schemas/Error"
}

Related guidance

Request errors and safe retries · Troubleshooting