Task Update API

Updates the status of a user activity task for a specific wallet address. When a task is marked as completed, the system checks if all tasks in the activity are complete and automatically awards points if the entire activity is finished.

Endpoint Details

Method: POST
Path: /activities/task_update/{address}
Content-Type: application/json

POST https://api.example.com/api/v1/activities/task_update/{address}

Description

Updates the status of a user activity task for a specific wallet address. Points are awarded only when completing a task causes the entire activity to be finished.

Request Parameters

Path Parameters

Parameter	Type	Required	Description
`address`	string	✅	The abstract wallet address of the user

Example: 0xB1a53d719D61a78007f660A7277070BA52A43bF7

Request Body

{
  "externalKey": "collection-of-worlds-action",
  "status": "completed",
  "apiKey": "partner_api_testing"
}

Field	Type	Required	Description
`externalKey`	string	✅	External identifier for the quest task
`status`	string	✅	Task status. Must be one of: `completed`, `rejected`
`apiKey`	string	✅	Partner API key for authentication

Request Headers

Header	Description	Example
`Content-Type`	Must be `application/json`	`application/json`

Response Format

Success Response with Points Awarded

HTTP Status: 200 OK

This response is returned when completing the task causes the entire activity to be finished, resulting in points being awarded.

{
  "updatedTask": {
    "id": "task_123456",
    "externalKey": "play-the-game",
    "status": "completed",
    "address": "0xB1a53d719D61a78007f660A7277070BA52A43bF7",
    "createdAt": "2025-07-01T09:15:00Z",
    "updatedAt": "2025-07-02T10:30:00Z",
    "completedAt": "2025-07-02T10:30:00Z"
  },
  "transaction": {
    "id": "txn_789012",
    "userId": "user_345678",
    "points": 100,
    "type": "task_completion",
    "description": "Completed task: play-the-game",
    "createdAt": "2025-07-02T10:30:00Z",
    "status": "confirmed"
  }
}

Response Fields

Field	Type	Description
`updatedTask`	object	The updated task object
`transaction`	object	Transaction details if points were awarded, `null` otherwise

Task Object

Field	Type	Description
`id`	string	Unique task identifier
`externalKey`	string	External identifier for the quest task
`status`	string	Current task status (`completed` or `rejected`)
`address`	string	The abstract wallet address of the user
`createdAt`	string	Task creation timestamp in ISO 8601 format (UTC)
`updatedAt`	string	Task last update timestamp in ISO 8601 format (UTC)
`completedAt`	string	Task completion timestamp in ISO 8601 format (UTC), nullable
`rejectedAt`	string	Task rejection timestamp in ISO 8601 format (UTC), nullable

Transaction Object

Field	Type	Description
`id`	string	Unique transaction identifier
`userId`	string	User identifier
`points`	integer	Number of points awarded
`type`	string	Transaction type
"description"	string	Transaction description
`createdAt`	string	Transaction creation timestamp in ISO 8601 format (UTC)
`status`	string	Transaction status

Example Implementation

const axios = require('axios');
 
async function updateTaskStatus(address, externalKey, status, apiKey) {
  try {
    const response = await axios.post(
      `https://api.example.com/api/v1/activities/task_update/${address}`,
      {
        externalKey: externalKey,
        status: status,
        apiKey: apiKey
      },
      {
        headers: {
          'Content-Type': 'application/json'
        }
      }
    );
 
    if (response.data.transaction) {
      console.log('Points awarded:', response.data.transaction.points);
    } else {
      console.log('Task completed, but activity not finished yet');
    }
 
    return response.data;
  } catch (error) {
    if (error.response) {
      console.error('Error:', error.response.data.message);
    } else {
      console.error('Request failed:', error.message);
    }
    throw error;
  }
}
 
// Usage
updateTaskStatus(
  '0xB1a53d719D61a78007f660A7277070BA52A43bF7',
  'collection-of-worlds-action',
  'completed',
  'partner_api_testing'
);

Important Notes

ℹ️

Points Award Logic: Points are only awarded when completing a task causes the entire activity to be finished. If other tasks in the activity are still incomplete, the transaction field will be null.

⚠️

Task Status: Once a task is marked as completed or rejected, it cannot be changed. Attempting to update an already completed task will result in a 409 Conflict error.

🔑

API Key Security: Always keep your API key secure. Never expose it in client-side code or commit it to version control.

Testing

🧪

Test your implementation with various scenarios:

Valid task completion that finishes an activity (should return transaction)
Valid task completion that doesn't finish an activity (should return null transaction)
Task rejection
Invalid API key
Non-existent wallet address
Non-existent task externalKey
Attempting to update an already completed task
Invalid status value

Servers

The API is available on the following servers:

Local Development: http://localhost:3000/api/v1
Production: https://api.example.com/api/v1
Mock Server: https://virtserver.swaggerhub.com/ygg-2e6/taskapi/1.0.0

Overview Overview