REST API

Alpaca Issue Tracker registers custom REST routes under the alpaca/v1 namespace and also filters selected WordPress core comment routes for issue comments.

Most write routes require a valid WordPress REST nonce. Same-origin JavaScript requests normally send the nonce with the X-WP-Nonce header through wp.apiFetch. Some endpoints also accept a nonce request parameter where the code explicitly supports it.

Method Names

This reference uses plain HTTP method names. In code, some endpoints use WordPress REST constants:

• WP_REST_Server::READABLE: GET.
• WP_REST_Server::CREATABLE: POST.
• WP_REST_Server::EDITABLE: POST, PUT, or PATCH.
• WP_REST_Server::DELETABLE: DELETE.

Permissions

Permissions are checked through Alpaca\Helpers::user_can() and Alpaca\Helpers::validate_rest_nonce_permission().

Common permission actions:

Custom permission behavior should use the alpaca_user_can filter documented in …/reference/core-and-admin.md.

Issue Endpoints

Create Issue

POST /wp-json/alpaca/v1/submit

Expected JSON payload includes:

{
  "userinput": {
    "feedback": "Issue title or report text",
    "includeContext": true,
    "isHighPriority": false
  }
}

When includeContext is true, the endpoint can store contextual capture data from client, server, wp, headers, and errors payload sections.

Update Issue

POST /wp-json/alpaca/v1/update/{id}

Supported JSON fields include:

{
  "title": "Updated title",
  "content": "Updated issue body",
  "post_parent": 123,
  "taxonomies": {
    "alpaca_status": [51],
    "alpaca_label": [88],
    "alpaca_assignee": ["user-slug"]
  },
  "meta": {
    "high_priority": true
  }
}

alpaca_assignee expects WordPress user slugs and resolves them to assignee taxonomy terms.

Create Subissue

POST /wp-json/alpaca/v1/subissues

Expected JSON payload:

{
  "parent_id": 123,
  "content": "Checklist item title"
}

Deleted Items

GET /wp-json/alpaca/v1/deleted-items

Supported query parameters:

Board And Status Endpoints

Update Board

POST /wp-json/alpaca/v1/board

Expected JSON payload is an array of columns:

[
  {
    "id": 51,
    "issues": [123, 124, 125]
  }
]

Update Status

POST /wp-json/alpaca/v1/status/{id}

Supported JSON fields:

{
  "name": "In Review",
  "term_score": 30
}

term_score must be numeric and inside the allowed status score range.

Users, Labels, And Watchlist Endpoints

Create Or Update Label

Supported JSON fields:

{
  "name": "Design",
  "color": "#172b4d"
}

Update Watchlist

Preferred JSON payload for replacing the user’s watchlist:

{
  "watchlist": [123, 124]
}

Backward-compatible JSON payload for toggling one issue:

{
  "issue_id": 123
}

Notification Endpoints

Notification Inbox Query Parameters

GET /wp-json/alpaca/v1/notification-inbox

Mark Inbox Items

POST /wp-json/alpaca/v1/notification-inbox/mark-read

POST /wp-json/alpaca/v1/notification-inbox/mark-unread

Expected JSON payload:

{
  "item_ids": [12, 13]
}

Notification Preferences

Update payloads use a preferences object:

{
  "preferences": {
    "instant": {},
    "digest": {}
  }
}

Notification Templates

Template update, preview, and test endpoints accept:

{
  "subject": "{{issue_title}} updated",
  "body": "<!-- wp:paragraph --><p>{{comment}}</p><!-- /wp:paragraph -->"
}

Attachment Endpoints

Upload Attachment

POST /wp-json/alpaca/v1/comment-attachments

Expected multipart form data:

The upload uses WordPress allowed MIME types and stores the file in an issue-specific upload directory.

Delete Attachment

POST /wp-json/alpaca/v1/comment-attachments/delete

Expected JSON or form fields:

Presence, Capture, And Proxy Endpoints

Image Proxy

GET /wp-json/alpaca/v1/proxy

Supported query parameters:

The proxy rejects unsafe private or reserved IP targets.

WordPress Core Comment Routes

Issue comments use WordPress comments with the issuecomment type, so the plugin extends selected WordPress core comment routes instead of registering separate comment CRUD routes.

For hidden issue comments, REST reads must explicitly target the issue comment type and opt into visibility:

comment_type=issuecomment
alpaca_include_hidden_comments=1
context=edit

Collection requests that include a post parameter must target alpaca_issue posts. Comment creation also requires an alpaca_issue post target.

REST Extension Hooks

Response Object Filter

alpaca_rest_response_object

Filter the final REST response object.

Example: add a custom header to successful Alpaca Issue Tracker REST responses.

add_filter(
	'alpaca_rest_response_object',
	static function ( $response, $action_type, $data, $status ) {
		if ( $status >= 200 && $status < 300 ) {
			$response->header( 'X-Alpaca-Handled', '1' );
		}

		return $response;
	},
	10,
	4
);

REST Root Filter

alpaca_rest_api_root

Filter the REST API root used by localized JavaScript settings.

Example: point Alpaca Issue Tracker REST requests at a custom REST root.

add_filter(
	'alpaca_rest_api_root',
	static function ( $root ) {
		return trailingslashit( home_url( '/wp-json/' ) );
	}
);

Private Comment Visibility Filters

alpaca_private_comments_rest_visibility_param customizes the request parameter used to opt into hidden issue comments.

alpaca_private_comments_user_can_view_type customizes who can view private issue comments by comment type.

Example: restrict hidden issue comments to administrators.

add_filter(
	'alpaca_private_comments_user_can_view_type',
	static function ( $allowed, $comment_type ) {
		if ( 'issuecomment' === $comment_type ) {
			return current_user_can( 'manage_options' );
		}

		return $allowed;
	},
	10,
	2
);

REST Lifecycle Actions

• alpaca_rest_response fires for every wrapped Alpaca Issue Tracker REST response.
• alpaca_rest_{action_type} fires for successful responses with an action type.
• alpaca_rest_error_{action_type} fires for error responses with an action type.