Skip to content

BirthdayAPI.md

Latest commit

 

History

History
246 lines (171 loc) · 16.7 KB

BirthdayAPI.md

File metadata and controls

246 lines (171 loc) · 16.7 KB

BirthdayAPI

Overview

The BirthdayAPI automates fetching, managing, and processing subscriber birthdays every week.

It collects birthday data every Monday and triggers a robot to process delivery tasks a few days before each event. A site sends birthday cards based on the subscribers' needs every year. These subscribers are so busy that they left this process of wishing thier loved ones with the list of items, needs and they go on with thier own work. THe site atomates the process using the APIs, Agentetic Robots, Delivery usinf Autonomous Vechicles. Write a BirthdayAPI which helps to gets data about that weeks' birthday people, makes a list collects details whenever Monday begins. On a dialy basis, an Highly secured Agentetic robot gets this data from the site using an API so that it processes and send the cards either couple of days before the birthday, giving it some time to delilver. There are endpoints to reach the address of the subscribers, the data on thier likings, gifts, coupons, etc. Also write an API for the delivery Agentic AI who take cares of the delivery at the door. This will have address, route of delivery ets.

Base URL

https://api.birthdayservice.com/v1

Main Functions

  • Fetch birthdays of the week
  • Retrieve subscriber details (likes, gifts, coupons, address)
  • Schedule card creation and delivery
  • Notify delivery robots in advance

Endpoints

GET /birthdays/week

Fetch all subscribers with birthdays in the current week.

Request Example:

GET /birthdays/week

Response:

{
  "weekStart":"2025-10-13",
  "weekEnd":"2025-10-19",
  "birthdays":[
    {
      "subscriberId":"S1001",
      "name":"Ava Johnson",
      "birthday":"2025-10-15",
      "daysUntilBirthday":2
    },
    {
      "subscriberId":"S1020",
      "name":"Liam Brown",
      "birthday":"2025-10-18",
      "daysUntilBirthday":5
    }
  ]
}

GET /subscribers/

Fetch complete subscriber details including preferences.

Example Request:

GET /subscribers/S1001

Response:

{
  "subscriberId":"S1001",
  "name":"Ava Johnson",
  "birthday":"2025-10-15",
  "address":"42 Elm Street, Boston, MA",
  "preferences":{
    "cardTheme":"Floral",
    "giftType":"Perfume",
    "couponPreference":"Amazon Gift Card"
  }
}

POST /birthdays/schedule

Triggered every Monday — collects all birthdays of the week and schedules deliveries.

Example Request:

POST /birthdays/schedule

Response:

{
  "message":"Weekly schedule created successfully",
  "totalBirthdays":48,
  "deliveryQueued":45
}

POST /birthdays/notify

Notify Agentic Robots to begin card processing.

Example Request:

POST /birthdays/notify
{
  "robotId": "AR-9001",
  "scheduledDate": "2025-10-13"
}

Response:

{
  "status":"success",
  "message":"Robot AR-9001 notified for this week’s birthdays."
}

2. DeliveryAPI

Overview

The DeliveryAPI is used by the Agentic AI delivery robots to plan routes, deliver birthday cards, and confirm successful delivery.

Base URL

https://api.deliveryservice.com/v1

🛠️ Endpoints

GET /delivery/routes

Get optimized delivery route for today’s deliveries.

Example Request:

GET /delivery/routes?date=2025-10-14

Response:

{
  "date":"2025-10-14",
  "route":[
    {
      "deliveryId":"D-2001",
      "subscriberId":"S1001",
      "address":"42 Elm Street, Boston, MA",
      "ETA":"09:30 AM",
      "packageType":"Birthday Card"
    },
    {
      "deliveryId":"D-2002",
      "subscriberId":"S1020",
      "address":"89 Maple Avenue, New York, NY",
      "ETA":"12:45 PM",
      "packageType":"Card + Gift"
    }
  ]
}

POST /delivery/confirm

Delivery robot updates the status after successful drop-off.

Request:

POST /delivery/confirm
{
  "deliveryId": "D-2001",
  "status": "Delivered",
  "timestamp": "2025-10-14T09:32:00Z",
  "recipientSignature": "Ava Johnson"
}

Response:

{
  "status":"success",
  "message":"Delivery D-2001 confirmed."
}

GET /delivery/status/

Fetch status of a specific delivery.

Example Request:

GET /delivery/status/D-2001

Response:

{
  "deliveryId":"D-2001",
  "status":"Delivered",
  "timestamp":"2025-10-14T09:32:00Z"
}

Security

All API calls are secured using:

  • API Keys for authentication
  • Encrypted payloads for personal data
  • HTTPS-only transport

Workflow Summary

Day Process Responsible API
Monday Collect weekly birthdays BirthdayAPI (/birthdays/schedule)
Tuesday–Saturday Robots process and prepare cards BirthdayAPI + internal robot logic
Delivery Day Send via autonomous vehicles DeliveryAPI
After Delivery Confirm completion DeliveryAPI (/delivery/confirm)