API Endpoints Report

1. API Documentation

• Live API documentation: https://neighborship.app/api/docs/
• Generated OpenAPI schema: https://neighborship.app/api/schema/
• Detailed API documentation generated using OpenAPI schema: API Documentation

The final release publishes its API surface under the following namespaces:

• /api/auth/
• /api/profiles/
• /api/mentorship/
• /api/messages/
• /api/notifications/

This is consistent with the current backend route configuration on the dev branch, and the live documentation already exposes the final published endpoint surface clearly enough for report purposes. Deprecated milestone endpoints are not part of the published final route list anymore.

2. Sample Usage Scenarios

Note: the JSON responses below were captured from real calls against the existing seeded Docker backend on the main branch. The seeded usernames and seeded story objects are deterministic, while generated UUIDs depend on the current seeded database instance. In practice, these UUIDs can be rediscovered reproducibly from the same seed data through list endpoints such as GET /api/mentorship/matches/me/, GET /api/mentorship/meeting-sessions/me/, and GET /api/profiles/me/tags/.

Scenario 1. Community Member Publishes a Community Post With Tags

• Endpoint: POST /api/profiles/tags/{tag_id}/posts/
• Scenario description: A community member shares an achievement post inside a community, tags an eligible mentorship connection, and chooses to also show the post on their public profile.
• Related requirements: 1.2.3.1, 1.2.3.4, 1.2.3.6, 1.2.3.8, 1.2.3.9, 1.2.3.10

Request:

curl -X POST "https://neighborship.app/api/profiles/tags/7ed42c71-c960-48e8-b64d-79dc35c40760/posts/" \
  -H "Authorization: Bearer <MENTOR_ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "achievement",
    "content": "We finished the API/report review checklist and shared the clearer demo flow with the community.",
    "media_url": "https://cdn.example.com/media/api-report-checklist.png",
    "show_on_profile": true,
    "tagged_users": ["mehmet-ali-ozdemir"]
  }'

Response:

{
  "id": "5461548a-e1e2-435c-b9aa-d0341ba141c7",
  "source_id": "cop:1aaaf4f7-d204-417e-9176-fe936f1838da",
  "category": "CoP",
  "event_type": "achievement",
  "content": "We finished the API/report review checklist and shared the clearer demo flow with the community.",
  "media_url": "https://cdn.example.com/media/api-report-checklist.png",
  "timestamp": "2026-05-14T10:28:12.865056+03:00",
  "created_at": "2026-05-14T10:28:12.865056+03:00",
  "last_edited": null,
  "show_on_profile": true,
  "community_id": "7ed42c71-c960-48e8-b64d-79dc35c40760",
  "community_slug": "student-product-builders",
  "author": {
    "id": "3d616a08-40fb-4c2f-895e-0b155ac80b88",
    "username": "deniz-arman",
    "display_name": "Deniz Arman",
    "picture_url": "https://randomuser.me/api/portraits/men/24.jpg",
    "title": "Senior Product Engineer",
    "show_initials_only": false
  },
  "tagged_users": [
    {
      "user_id": "0e6c4dc4-a6e6-4567-9908-7efb88413d65",
      "username": "mehmet-ali-ozdemir"
    }
  ]
}

Scenario 2. Mentor Creates a Community-Scoped Workshop

• Endpoint: POST /api/profiles/tags/{tag_id}/workshops/
• Scenario description: A mentor who is already a member of a community creates a workshop, the platform validates time and conflict rules, and the author is automatically enrolled as the first participant.
• Related requirements: 1.1.9.1, 1.1.9.2, 1.1.9.4, 1.2.3.4

Request:

curl -X POST "https://neighborship.app/api/profiles/tags/7ed42c71-c960-48e8-b64d-79dc35c40760/workshops/" \
  -H "Authorization: Bearer <MENTOR_ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Final Release API Review Clinic",
    "description": "A guided session on validating SRS alignment, API scenarios, and submission-ready evidence.",
    "scheduled_at": "2026-06-05T16:00:00Z",
    "end_at": "2026-06-05T17:30:00Z",
    "max_participants": 12
  }'

Response:

{
  "id": "249e82ef-ef6c-436d-ad0f-1860215a4137",
  "community_id": "7ed42c71-c960-48e8-b64d-79dc35c40760",
  "community_name": "Student Product Builders",
  "author": {
    "id": "3d616a08-40fb-4c2f-895e-0b155ac80b88",
    "username": "deniz-arman",
    "display_name": "Deniz Arman",
    "picture_url": "https://randomuser.me/api/portraits/men/24.jpg",
    "title": "Senior Product Engineer"
  },
  "title": "Final Release API Review Clinic",
  "description": "A guided session on validating SRS alignment, API scenarios, and submission-ready evidence.",
  "scheduled_at": "2026-06-05T19:00:00+03:00",
  "end_at": "2026-06-05T20:30:00+03:00",
  "max_participants": 12,
  "participant_count": 1,
  "is_full": false,
  "participants": [
    {
      "id": "561653de-d2ba-474a-8696-940c24006b5a",
      "participant": {
        "id": "3d616a08-40fb-4c2f-895e-0b155ac80b88",
        "username": "deniz-arman",
        "display_name": "Deniz Arman",
        "picture_url": "https://randomuser.me/api/portraits/men/24.jpg",
        "title": "Senior Product Engineer"
      },
      "joined_at": "2026-05-14T10:28:12.954226+03:00",
      "show_on_profile": false
    }
  ],
  "status": "SCHEDULED",
  "current_user_enrolled": true,
  "created_at": "2026-05-14T10:28:12.944179+03:00",
  "updated_at": "2026-05-14T10:28:12.944181+03:00"
}

Scenario 3. Match Participant Logs a Shared Journey Milestone

• Endpoint: POST /api/mentorship/matches/{match_id}/journey/events/
• Scenario description: A match participant records a manual progress update in the shared mentorship journey and optionally exposes that milestone on their own profile.
• Related requirements: 1.1.14.1, 1.1.14.2, 1.1.14.3, 1.1.14.4, 1.1.14.5

Request:

curl -X POST "https://neighborship.app/api/mentorship/matches/5aa3cb5e-29f2-4893-a575-0c7f0a356024/journey/events/" \
  -H "Authorization: Bearer <MENTOR_ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "event_type": "progress",
    "content": "Reviewed the landing flow again and agreed on a smaller first release scope for the student project.",
    "media_url": "https://cdn.example.com/media/final-scope-note.png",
    "show_on_profile": true
  }'

Response:

{
  "id": "a2ed3792-c9bb-45f4-9fd9-a876ece5e9ab",
  "source_id": "mcte:62fd3b6e-79f2-4105-a303-cc0959adda60",
  "event_type": "progress",
  "content": "Reviewed the landing flow again and agreed on a smaller first release scope for the student project.",
  "media_url": "https://cdn.example.com/media/final-scope-note.png",
  "timestamp": "2026-05-14T10:28:12.779205+03:00",
  "created_at": "2026-05-14T10:28:12.779205+03:00",
  "last_edited": null,
  "show_on_profile": true,
  "actor_role": "mentor",
  "author": {
    "id": "3d616a08-40fb-4c2f-895e-0b155ac80b88",
    "username": "deniz-arman",
    "display_name": "Deniz Arman",
    "picture_url": "https://randomuser.me/api/portraits/men/24.jpg",
    "title": "Senior Product Engineer"
  }
}

Scenario 4. Mentee Updates Workshop Attendance Visibility on Their Profile

• Endpoint: PATCH /api/profiles/me/workshops/attendance/{workshop_id}/
• Scenario description: A mentee updates one of their joined workshop attendance records so that the workshop is shown on their public profile.
• Related requirements: 1.1.9.5, 1.2.3.10

Request:

curl -X PATCH "https://neighborship.app/api/profiles/me/workshops/attendance/c59ddfae-42b4-4d9c-b7da-77433ed2d271/" \
  -H "Authorization: Bearer <MENTEE_ACCESS_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{
    "show_on_profile": true
  }'

Response:

{
  "id": "d35950ef-798f-4a2e-b1ce-3616dfd5eb26",
  "workshop_id": "c59ddfae-42b4-4d9c-b7da-77433ed2d271",
  "workshop_title": "MVP Feedback Hour",
  "workshop_description": "A group discussion on shrinking student product ideas into a believable first release.",
  "workshop_status": "SCHEDULED",
  "workshop_scheduled_at": "2026-05-18T18:30:00+03:00",
  "workshop_end_at": "2026-05-18T20:00:00+03:00",
  "community_id": "7ed42c71-c960-48e8-b64d-79dc35c40760",
  "community_name": "Student Product Builders",
  "author": {
    "id": "4e1ad1d9-fa0b-4626-9278-fdde3bb7581c",
    "username": "goksel-deniz-celik",
    "display_name": "Göksel Deniz Çelik",
    "picture_url": "https://randomuser.me/api/portraits/men/55.jpg",
    "title": "Full-Stack Project Mentor"
  },
  "joined_at": "2026-05-13T23:08:40.826763+03:00",
  "show_on_profile": true,
  "attendance_status": "attending"
}