arkipel_messages:query

Description: Query a message from a given id.

Request Schema

{
  "payload": {
    "type": "arkipel_messages:query",
    "message_id": "message_id_to_query"
  },
  "signature": "payload_ed25519_hex_signature",
  "source_public_key": "your_client_public_key"
}

Request Attributes

Response Schema

{
  "source_public_key": "community_public_key",
  "source_site": {
    "protocol": "http",
    "fqdn": "arkipel.localhost:3000"
  },
  "created_at": "2025-11-13T20:52:49Z",
  "signature": "8b6392d5550605bd6ccddf9c21ebec470de4b44e4b4deb746076e37ab61c5346e07e7c7c7cebb5bbee41cdd92a476bcd3f02373d146ec165b31c31fc31c9ce0d",
  "payload": {
    "message_id": "6916452112f746b2b4cf48c1",
    "type": "arkipel_messages:query",
    "message_type": "distributions:upsert",
    "original_payload": {
      "buyer": { "type": "households:upsert", "name": "Family Doe" },
      "template_id": 120884,
      "procured_on": "2026-02-14",
      "quantity": 1
    },
    "resource": { ... },
    "error": null,
    "status": "persisted"
  }
}

Response Attributes

  • See global response attributes
  • payload.message_id - String - The queried message ID
  • payload.message_type - String - The original message type (e.g., “distributions:upsert”, “people:upsert”)
  • payload.original_payload - Object - The complete payload originally sent by the client
  • payload.resource - Object, optional - The destination subject attributes if the message was successfully persisted
  • payload.error - String, optional - Error message if the message failed processing, includes documentation URL
  • payload.status - String - The message status: “pending”, “queued”, “persisted”, “failed”, “rejected”, etc.

Error Responses

Message Not Found

{
  "payload": {
    "type": "arkipel_messages:query"
  },
  "error": "No message found with payload#message_id='invalid_id'",
  "status": "not_found"
}

Missing Message ID

{
  "payload": {
    "type": "arkipel_messages:query"
  },
  "error": "No payload#message_id given",
  "status": "bad_request"
}

Real Life Example - Persisted Message

{
  "source_public_key": "bwyexzko74pnnjn741936fnaujxyhib9rpx8rggtejwnc3cz6ans",
  "source_site": {
    "protocol": "https",
    "fqdn": "arkipel.co"
  },
  "created_at": "2026-02-14T14:14:22Z",
  "signature": "0b7cf3e421c4d7e4212e2069fbfbfd6734d0809fa3603e492949dc5b948da691f277c601d48b9cbac2bebbfdf697e8e01aa93ff54ae53afab4c5c2272dea0400",
  "payload": {
    "message_id": "699082bf865f35b8849924b1",
    "type": "arkipel_messages:query",
    "message_type": "distributions:upsert",
    "original_payload": {
      "buyer": {
        "type": "households:upsert",
        "name": "Family Doe",
        "import_id": "F0001"
      },
      "template_id": 120884,
      "procured_on": "2026-02-14",
      "quantity": 1
    },
    "resource": {
      "id": 12345,
      "buyer_id": 67890,
      "buyer_type": "Household",
      "mode": "distribution",
      "procured_on": "2026-02-14",
      "created_at": "2026-02-14T14:14:22Z"
    },
    "error": null,
    "status": "persisted"
  }
}

Real Life Example - Failed Message

{
  "source_public_key": "bwyexzko74pnnjn741936fnaujxyhib9rpx8rggtejwnc3cz6ans",
  "source_site": {
    "protocol": "https",
    "fqdn": "arkipel.co"
  },
  "created_at": "2026-02-14T14:20:15Z",
  "signature": "a1b2c3d4e5f6...",
  "payload": {
    "message_id": "699082bf865f35b8849924c2",
    "type": "arkipel_messages:query",
    "message_type": "distributions:upsert",
    "original_payload": {
      "buyer": { "name": "Family Doe" },
      "template_id": 120884
    },
    "resource": {},
    "error": "Missing required key: buyer[:type]. The buyer must specify a type such as 'households:upsert' or 'people:upsert'. Received buyer payload with keys: [:name]. Please refer to https://devkit.arkipel.co/specs/mutations/distributions-upsert.html (Payload validation failed. Please refer to https://devkit.arkipel.co/specs/mutations/distributions-upsert.html)",
    "status": "failed"
  }
}

Usage Notes

  • The original_payload field allows you to see exactly what was sent in the original request, making it easy to identify issues
  • The message_type field helps you identify which specification to reference when troubleshooting
  • When status is “failed”, the error field will contain a descriptive message with a link to the relevant documentation
  • The resource field is only populated when the message was successfully processed (status: "persisted")