0 items
Sign in
Buy

Docs

GravityBoard Developer Docs (Hooks & REST API)

Estimated reading: 24 minutes

Updated on April 24, 2026

GravityBoard provides hooks that developers can use to extend or modify its functionality. Each section below shows the PHPDoc signature as it appears in the plugin source, followed by the exact do_action() or apply_filters() call. Versions listed in @since tags refer to GravityBoard releases.

Table of contents #

Actions #

Assignee actions

gk/gravityboard/assignees/added

/**
 * Fired when a user is assigned to an entry via the GravityBoard interface.
 *
 * @since 1.0
 *
 * @param int   $user_id  The ID of the user who was assigned.
 * @param int   $entry_id The ID of the entry that was updated.
 * @param array $feed     The feed associated with the board.
 * @param array $form     The form associated with the entry.
 */
do_action( 'gk/gravityboard/assignees/added', (int) $user_id, $entry_id, $feed, $form );

gk/gravityboard/assignees/removed

/**
 * Fired when a user is unassigned from an entry via the GravityBoard interface.
 *
 * @since 1.0
 *
 * @param int   $user_id  The ID of the user who was unassigned.
 * @param int   $entry_id The ID of the entry that was updated.
 * @param array $feed     The feed associated with the board.
 * @param array $form     The form associated with the entry.
 */
do_action( 'gk/gravityboard/assignees/removed', (int) $user_id, $entry_id, $feed, $form );

gk/gravityboard/assignees/updated

/**
 * Fired after entry assignees are successfully updated.
 *
 * @since 1.0
 *
 * @param int   $entry_id  The ID of the entry that was updated.
 * @param array $assignees The assignees for the entry.
 * @param array $feed      The feed associated with the board.
 * @param array $form      The form associated with the entry.
 */
do_action( 'gk/gravityboard/assignees/updated', (int) $entry_id, $assignees, $feed, $form );

Attachment actions

gk/gravityboard/attachments/added

/**
 * Runs when attachments have been added, before the notification is triggered.
 *
 * @since 1.0
 *
 * @param array $attachments The attachments array.
 * @param array $entry       The entry array.
 * @param array $feed        The feed array.
 */
do_action( 'gk/gravityboard/attachments/added', $attachments, $entry, $feed );

gk/gravityboard/attachments/removed

/**
 * Runs when attachments have been removed, before the notification is triggered.
 *
 * @since 1.0
 *
 * @param array  $updated_attachments     The updated attachments array.
 * @param array  $entry                   The entry array.
 * @param array  $feed                    The feed array.
 * @param string $attachment_id_to_delete The ID of the attachment that was deleted.
 */
do_action( 'gk/gravityboard/attachments/removed', $updated_attachments, $entry, $feed, $attachment_id_to_delete );

gk/gravityboard/attachments/updated

/**
 * Runs when attachments have been updated, before the notification is triggered.
 *
 * @since 1.0
 *
 * @param array $sanitized_attachments The sanitized attachments array.
 * @param array $entry                 The entry array.
 * @param array $feed                  The feed array.
 */
do_action( 'gk/gravityboard/attachments/updated', $sanitized_attachments, $entry, $feed );

Card actions

gk/gravityboard/card/added

/**
 * Runs when a card (entry) has been created, before the notification is triggered.
 *
 * @since 1.0
 *
 * @param array           $created_entry The created entry data.
 * @param array           $feed          The feed data.
 * @param WP_REST_Request $request       The REST request object.
 */
do_action( 'gk/gravityboard/card/added', $created_entry, $feed, $request );

gk/gravityboard/card/edited

/**
 * Runs when a card (entry) has been updated, before the notification is triggered.
 *
 * @since 1.0
 *
 * @param array $updated_entry The updated entry data.
 * @param array $feed          The feed data.
 * @param array $changes       The changes to the card; each element is a string of the field or meta key that was updated.
 */
do_action( 'gk/gravityboard/card/edited', $updated_entry, $feed, $changes );

gk/gravityboard/card/changed-lane

/**
 * Runs when a card (entry) has been moved to a new lane, before the notification is triggered.
 *
 * @since 1.0
 *
 * @param array $updated_entry  The updated entry data.
 * @param array $feed           The feed data.
 * @param int   $source_lane_id The ID of the source lane.
 * @param int   $target_lane_id The ID of the target lane.
 */
do_action( 'gk/gravityboard/card/changed-lane', $updated_entry, $feed, $source_lane_id, $target_lane_id );

gk/gravityboard/card/sorted

/**
 * Runs when a card (entry) has been sorted, before the notification is triggered.
 *
 * @since 1.0
 *
 * @param array $updated_entry  The updated entry data.
 * @param array $feed           The feed data.
 * @param int   $source_lane_id The ID of the lane with cards that were sorted.
 * @param array $ordered_ids    The ordered card IDs.
 */
do_action( 'gk/gravityboard/card/sorted', $updated_entry, $feed, $source_lane_id, $ordered_ids );

gk/gravityboard/card/deleted

/**
 * Runs when a card (entry) has been trashed or deleted, before the notification is triggered.
 *
 * @since 1.0
 *
 * @param array  $entry         The entry data.
 * @param array  $feed          The feed data.
 * @param string $deletion_mode The deletion mode ("trash" or "delete").
 */
do_action( 'gk/gravityboard/card/deleted', $entry, $feed, $deletion_mode );

Checklist actions

gk/gravityboard/checklists/updated

/**
 * Runs when checklists have been updated.
 *
 * @since 1.1
 *
 * @param ChecklistCollection $checklists The checklist collection.
 * @param array               $entry      The entry array.
 * @param array               $feed       The feed array.
 */
do_action( 'gk/gravityboard/checklists/updated', $checklists, $entry, $feed );

gk/gravityboard/checklists/item/added

/**
 * Runs when a checklist item has been added.
 *
 * @since 1.1
 *
 * @param array|WP_Error $entry    The entry data, or a WP_Error if the entry is not found.
 * @param ChecklistItem  $new_item The new checklist item.
 * @param array          $feed     The feed data.
 */
do_action( 'gk/gravityboard/checklists/item/added', Helpers::get_card( $entry_id ), $new_item, $feed );

gk/gravityboard/checklists/item/updated

/**
 * Runs when a checklist item has been updated.
 *
 * @since 1.1
 *
 * @param array|WP_Error      $entry      The entry data, or a WP_Error if the entry is not found.
 * @param ChecklistItem       $item       The checklist item.
 * @param ChecklistCollection $collection The updated checklists collection.
 * @param array               $feed       The feed data.
 */
do_action( 'gk/gravityboard/checklists/item/updated', Helpers::get_card( $entry_id ), $item, $checklist_collection, $feed );

gk/gravityboard/checklists/item/deleted

/**
 * Runs when a checklist item has been deleted.
 *
 * @since 1.1
 *
 * @param array|WP_Error      $entry      The entry data, or a WP_Error if the entry is not found.
 * @param ChecklistItem       $item       The deleted checklist item.
 * @param ChecklistCollection $checklists The updated checklists data.
 * @param array               $feed       The feed data.
 */
do_action( 'gk/gravityboard/checklists/item/deleted', Helpers::get_card( $entry_id ), $item, $collection, $feed );

gk/gravityboard/checklists/templates-applied

/**
 * Runs when checklist templates have been applied to an entry.
 *
 * @since 1.3
 *
 * @param ChecklistCollection $merged_collection The merged template collection that was applied.
 * @param array               $entry             The created entry data.
 * @param array               $applied_feed_ids  Array of feed IDs that were applied.
 * @param array               $form              The form data.
 * @param int                 $items_added       Number of items added from templates.
 */
do_action( 'gk/gravityboard/checklists/templates-applied', $merged_collection, $entry, $applied_feed_ids, $form, $items_added );

Lane actions

gk/gravityboard/lane/added

/**
 * Runs when a lane has been added.
 *
 * @since 1.0
 *
 * @param int   $new_lane_id     The ID of the new lane.
 * @param array $new_lane_choice The new lane choice.
 * @param array $feed            The feed data.
 */
do_action( 'gk/gravityboard/lane/added', $new_lane_id, $new_lane_choice, $this->feed );

gk/gravityboard/lane/edited

/**
 * Runs when a lane has been edited.
 *
 * @since 1.0
 *
 * @param array $form          The form data.
 * @param int   $lane_field_id The ID of the lane field.
 * @param array $feed          The feed data.
 */
do_action( 'gk/gravityboard/lane/edited', $this->form, $this->lane_field->id, $this->feed );

gk/gravityboard/lane/moved

/**
 * Runs when a lane has been moved.
 *
 * @since 1.0
 *
 * @param array $form          The form data.
 * @param int   $lane_field_id The ID of the lane field.
 * @param array $feed          The feed data.
 * @param int   $new_position  The new position of the lane.
 */
do_action( 'gk/gravityboard/lane/moved', $this->form, $this->lane_field->id, $this->feed, $new_position );

gk/gravityboard/lane/deleted

/**
 * Runs when a lane has been deleted.
 *
 * @since 1.0
 *
 * @param array $form          The form data.
 * @param int   $lane_field_id The ID of the lane field.
 * @param array $feed          The feed data.
 * @param int   $lane_id       The ID of the lane that was deleted.
 */
do_action( 'gk/gravityboard/lane/deleted', $this->form, $this->lane_field->id, $this->feed, $lane_id );

Voting actions

gk/gravityboard/voting/vote-added

/**
 * Fired when a user's vote is added on a card.
 *
 * @since 1.4.0
 *
 * @param int $entry_id   The entry (card) ID.
 * @param int $user_id    The voting user ID.
 * @param int $feed_id    The feed ID.
 * @param int $new_weight The resulting vote weight.
 */
do_action( 'gk/gravityboard/voting/vote-added', $entry_id, $user_id, $feed_id, $new_weight );

gk/gravityboard/voting/vote-removed

/**
 * Fired when a user's vote is removed from a card.
 *
 * @since 1.4.0
 *
 * @param int $entry_id   The entry (card) ID.
 * @param int $user_id    The voting user ID.
 * @param int $feed_id    The feed ID.
 * @param int $new_weight The resulting vote weight after removal.
 */
do_action( 'gk/gravityboard/voting/vote-removed', $entry_id, $user_id, $feed_id, $new_weight );

AJAX actions

gk/gravityboard/ajax/register-routes

/**
 * Allow other plugins to register REST routes on the GravityBoard Ajax instance.
 *
 * @since 1.0.0
 *
 * @param Ajax $ajax The Ajax instance.
 */
do_action( 'gk/gravityboard/ajax/register-routes', $this );

Filters #

Card and data filters

gk/gravityboard/card/data

/**
 * Filter the card data returned from the entry.
 *
 * @since 1.1
 *
 * @param array $card  The card data.
 * @param array $entry The entry data.
 * @param array $feed  The feed data.
 *
 * @return array
 */
return apply_filters( 'gk/gravityboard/card/data', $card, $entry, $feed );

gk/gravityboard/card/update-card

/**
 * Allow plugins to add additional changes to the card when it is updated.
 *
 * @since 1.0
 *
 * @param array           $changes The changes to the card; each element is a string of the field or meta key that was updated.
 * @param WP_REST_Request $request The REST request object.
 * @param array           $entry   The entry data.
 * @param array           $feed    The feed data.
 *
 * @return array
 */
$additional_changes = apply_filters( 'gk/gravityboard/card/update-card', [], $request, $entry, $feed );

gk/gravityboard/data/lanes

/**
 * Filter lanes data before returning to the frontend.
 *
 * @since 1.0
 *
 * @param array $lanes   The lanes data, including their cards.
 * @param array $entries The entries data.
 * @param array $feed    The feed data.
 *
 * @return array
 */
$lanes = apply_filters( 'gk/gravityboard/data/lanes', $lanes, $entries, $feed );

gk/gravityboard/lane/sorted-cards

/**
 * Filter the sorted cards within a lane.
 *
 * @since 1.4.0
 *
 * @param array $cards The sorted cards.
 * @param array $lane  The lane data.
 * @param array $feed  The feed data.
 *
 * @return array
 */
$lane['cards'] = apply_filters( 'gk/gravityboard/lane/sorted-cards', $lane['cards'], $lane, $feed );

Board and rendering filters

gk/gravityboard/board-settings

/**
 * Filter the board settings before they are passed to the frontend React application.
 *
 * @since 1.0
 *
 * @param array $board_settings The board settings.
 * @param int   $feed_id        The ID of the feed.
 *
 * @return array The board settings.
 */
$board_settings = apply_filters( 'gk/gravityboard/board-settings', $board_settings, $feed_id );

gk/gravityboard/translation-overrides

/**
 * Filters the translation overrides for the GravityBoard.
 *
 * @since 1.0
 *
 * @param array $translation_overrides The translation overrides.
 * @param int   $feed_id               The ID of the feed.
 *
 * @return array The translation overrides, with each key being the original string and the value being an array of strings to replace it with.
 */
$translation_overrides = apply_filters( 'gk/gravityboard/translation-overrides', [], $feed_id );

gk/gravityboard/renderer/css-variable-overrides

/**
 * Filters the CSS variable overrides for the GravityBoard.
 *
 * @since 1.0
 *
 * @param array $css_overrides The CSS overrides, with the key as the full CSS variable name and the value as the CSS value.
 * @param array $feed          The feed.
 *
 * @return array
 */
$css_overrides = apply_filters( 'gk/gravityboard/renderer/css-variable-overrides', $css_overrides, $feed );

Permissions filters

gk/gravityboard/permissions/admin-has-full-access

/**
 * Filters whether an admin user bypasses all board permission checks.
 *
 * @since 1.4.0
 *
 * @param bool $has_full_access Whether the user has full access. Default: true for admins.
 * @param int  $user_id         The user ID being checked.
 *
 * @return bool
 */
$has_full_access = (bool) apply_filters( 'gk/gravityboard/permissions/admin-has-full-access', $has_full_access, $user_id );

See Admin bypass for GravityBoard permissions for usage examples and context.

Feature-specific filters

gk/gravityboard/notes/filter-by-board

/**
 * Filter whether to filter notes by board so only notes created on the current board are returned.
 *
 * @since 1.0
 *
 * @param bool $filter_notes_by_board Whether to filter notes by board.
 * @param int  $feed_id               The feed ID.
 *
 * @return bool
 */
$filter_notes_by_board = apply_filters( 'gk/gravityboard/notes/filter-by-board', false, $feed_id );

gk/gravityboard/checklists/export-value

/**
 * Filters the export text for checklists in CSV or other export formats.
 *
 * @since 1.1
 *
 * @param string              $export_text The export text, which is a string of checklist items and their statuses.
 * @param ChecklistCollection $checklists  The checklists collection.
 *
 * @return string The filtered export text.
 */
$export_text = apply_filters( 'gk/gravityboard/checklists/export-value', $export_text, $checklists );

gk/gravityboard/voting/can-spend-vote

/**
 * Filters whether a user can spend a vote.
 *
 * Return true to allow or a WP_Error to deny with a message.
 *
 * @since 1.4.0
 *
 * @param true|WP_Error $allowed  Whether the vote is allowed.
 * @param int           $feed_id  The feed ID.
 * @param int           $user_id  The user ID.
 * @param int           $entry_id The entry (card) ID.
 * @param array         $budget   Budget info from get_budget().
 *
 * @return bool|WP_Error
 */
$allowed = apply_filters( 'gk/gravityboard/voting/can-spend-vote', true, $feed_id, $user_id, $entry_id, $budget );

gk/gravityboard/voting/budget-total

/**
 * Filters the total vote budget for a user.
 *
 * Allows role-based budgets, dynamic budgets, etc.
 *
 * @since 1.4.0
 *
 * @param int $total   The total budget (0 = unlimited).
 * @param int $feed_id The feed ID.
 * @param int $user_id The user ID.
 *
 * @return int
 */
return (int) apply_filters( 'gk/gravityboard/voting/budget-total', $total, $feed_id, $user_id );

gk/gravityboard/merge-tags/assignee-user-id

/**
 * Filter the assignee user ID used when resolving assignee merge tags.
 *
 * @internal Do not rely on this filter; it is designed for internal use only.
 *
 * @since 1.0
 *
 * @param int|null $assignee_user_id The assignee user ID.
 * @param array    $entry            The entry object.
 *
 * @return int|null
 */
$assignee_user_id = apply_filters( 'gk/gravityboard/merge-tags/assignee-user-id', null, $entry );

REST API #

GravityBoard uses the WordPress REST API to fetch data. The API is available at https://your-site.com/wp-json/gravityboard/v1/boards/.

The API is used to interact with the cards and lanes.

Cards (entries)

MethodEndpointDescriptionPayload Fields (JSON)
GET/gravityboard/v1/boards/‍{feed_id}/cardsRetrieve all cards for the specified board.N/A
POST/gravityboard/v1/boards/‍{feed_id}/cardsCreate a new card on the specified board.

input_values (object): Key-value pairs of field IDs and their values.

lane_id (string, optional): The ID of the lane to add the card to.

PATCH/gravityboard/v1/boards/‍{feed_id}/cards/{entry_id}Update an existing card.

input_values (object): Key-value pairs of field IDs and their new values.

assignees (array, optional): Array of user IDs to assign.

PUT/gravityboard/v1/boards/‍{feed_id}/cards/{entry_id}/moveMove a card (e.g., to a new lane or reorder within the same lane).

lane_id (string): The ID of the target lane.

position (integer): The new zero-based index of the card within the lane.

DELETE/gravityboard/v1/boards/‍{feed_id}/cards/{entry_id}Delete a card.N/A

Lanes

Lane IDs are determined by the order of choices in the mapped field, starting from zero.

For example, if a field has choices “Backlog”, “To Do”, “In Progress”, “Testing”, “Done”, the corresponding lane IDs will be 0, 1, 2, 3, 4.

MethodEndpointDescriptionPayload Fields (JSON)
POST/gravityboard/v1/boards/‍{feed_id}/lanesCreate a new lane for the specified board.value (string): The value/name of the new lane.
PATCH/gravityboard/v1/boards/‍{feed_id}/lanes/{lane_id}Update an existing lane’s properties (e.g., name).value (string): The new value/name for the lane.
PUT/gravityboard/v1/boards/‍{feed_id}/lanes/{lane_id}/move

Moves a lane to a new position. The {lane_id} in the URL identifies the lane to be moved. The position in the payload indicates the new zero-based index for the lane.

Example: to move lane 3 to the second position (index 1) for board {feed_id}, the request would be to PUT /gravityboard/v1/boards/{feed_id}/lanes/3/move with payload {"lane_id": "3", "position": 1}.

lane_id (string): The ID of the lane being moved.

position (integer): The new zero-based index for the lane.

DELETE/gravityboard/v1/boards/‍{feed_id}/lanes/{lane_id}Delete a lane.N/A

Notes

MethodEndpointDescriptionPayload Fields (JSON)
GET/gravityboard/v1/boards/‍{feed_id}/cards/{entry_id}/notesRetrieve all notes for a specific card (entry).N/A
POST/gravityboard/v1/boards/‍{feed_id}/cards/{entry_id}/notesAdd a new note to a specific card.note (string): The content of the note.
PUT/gravityboard/v1/boards/‍{feed_id}/cards/{entry_id}/notes/{note_id}Update an existing note on a card.note (string): The updated content of the note.
DELETE/gravityboard/v1/boards/‍{feed_id}/cards/{entry_id}/notes/{note_id}Delete a note from a card.N/A

Attachments

MethodEndpointDescriptionPayload Fields (Form Data)
POST/gravityboard/v1/boards/{feed_id}/cards/‍{entry_id}/attachmentsAdd a new attachment to a specific card.file (file): The file to be uploaded.
DELETE/gravityboard/v1/boards/{feed_id}/cards/‍{entry_id}/attachments/{attachment_id}Delete an attachment from a card.N/A

Checklists

MethodEndpointDescriptionPayload Fields (JSON)
GET/gravityboard/v1/boards/{feed_id}/cards/‍{entry_id}/checklistsRetrieve all checklists for a specific card.N/A
PUT/gravityboard/v1/boards/{feed_id}/cards/‍{entry_id}/checklistsUpdate entire checklists for a card.checklists (array): Array of checklist objects.
POST/gravityboard/v1/boards/{feed_id}/cards/‍{entry_id}/checklists/{checklist_id}/itemsAdd a new checklist item to a card.label (string): The item label.
PUT/gravityboard/v1/boards/{feed_id}/cards/‍{entry_id}/checklists/{checklist_id}/items/{item_id}Update an existing checklist item.

label (string, optional): New item label.

is_complete (boolean, optional): Completion status.

position (integer, optional): New position.

DELETE/gravityboard/v1/boards/{feed_id}/cards/‍{entry_id}/checklists/{checklist_id}/items/{item_id}Delete a checklist item from a card.N/A

Authentication

The API is authenticated using the WordPress REST API authentication method.

Permissions

The API is protected by the permissions associated with the feed; that is why the feed ID is required in the URL. See Admin bypass for GravityBoard permissions for details on how administrator access interacts with these checks.

Was this page helpful?

Table Of Contents