openapi: 3.0.3
info:
  title: 'Hodhod Api V1 - Beta'
  description: ''
  version: 1.0.0
servers:
  -
    url: 'https://gohodhod.com'
tags:
  -
    name: Newsletter
    description: ''
  -
    name: Issues
    description: ''
  -
    name: Subscribers
    description: ''
components:
  securitySchemes:
    default:
      type: http
      scheme: bearer
      description: 'You can retrieve your token by visiting your dashboard and clicking <b>Generate API token</b>.'
security:
  -
    default: []
paths:
  /api/v1/newsletter/profile-info:
    get:
      summary: 'Returns profile info for the newsletter.'
      operationId: returnsProfileInfoForTheNewsletter
      description: ''
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  newsletter_id: 7634
                  title: 'Deserunt voluptatem dolores soluta atque.'
                  author: 'وداد المقبل'
                  description: 'Dolorem sint nulla eveniet harum sit consequuntur et esse sit incidunt voluptate non nulla.'
                  image: 'https://gohodhod.com/images/img-avatar-newsletter.png'
                  primary_color: '#13b981'
                  slug: ahmad73
                  profile_url: 'https://gohodhod.com/@ahmad73'
                  externa_links: null
                properties:
                  newsletter_id:
                    type: integer
                    example: 7634
                  title:
                    type: string
                    example: 'Deserunt voluptatem dolores soluta atque.'
                  author:
                    type: string
                    example: 'وداد المقبل'
                  description:
                    type: string
                    example: 'Dolorem sint nulla eveniet harum sit consequuntur et esse sit incidunt voluptate non nulla.'
                  image:
                    type: string
                    example: 'https://gohodhod.com/images/img-avatar-newsletter.png'
                  primary_color:
                    type: string
                    example: '#13b981'
                  slug:
                    type: string
                    example: ahmad73
                  profile_url:
                    type: string
                    example: 'https://gohodhod.com/@ahmad73'
                  externa_links:
                    type: string
                    example: null
                    nullable: true
      tags:
        - Newsletter
    patch:
      summary: 'Update profile info for the newsletter.'
      operationId: updateProfileInfoForTheNewsletter
      description: ''
      parameters: []
      responses: {  }
      tags:
        - Newsletter
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                title:
                  type: string
                  description: ''
                  example: 'نشرة هدهد البريدية'
                author:
                  type: string
                  description: 'يجب ألا يتجاوز 255 حرفًا'
                  example: 'عماد الدين'
                  nullable: true
                description:
                  type: string
                  description: 'يجب ألا يتجاوز 512 حرفًا'
                  example: 'Labore esse ipsum in ducimus natus.'
                  nullable: true
                primary_color:
                  type: string
                  description: '(hex) يجب أن يكون كود لوني صحيح'
                  example: '#146ec2'
                  nullable: true
                slug:
                  type: string
                  description: 'لاحقة النشرة على هدهد (يمكن أن تحوي فقط أحرف لاتينية، أرقام، شرطة أفقية أو شرطة تحتية؟)'
                  example: odit
  /api/v1/newsletter/profile-image:
    post:
      summary: "Update newsletter's profile image."
      operationId: updateNewslettersProfileImage
      description: ''
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: boolean
                example: true
      tags:
        - Newsletter
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                image:
                  type: string
                  format: binary
                  description: 'يجب أن يكون value صورةً. يجب أن لا يتجاوز حجم الملف value 512 كيلوبايت.'
              required:
                - image
  /api/v1/issues:
    get:
      summary: "Fetch a listing of the newsletter's issues."
      operationId: fetchAListingOfTheNewslettersIssues
      description: ''
      parameters:
        -
          in: query
          name: status
          description: '(optional) Filters issue based on status. Can only be: "draft", "published" or "scheduled"'
          example: null
          required: false
          schema:
            type: string
            description: '(optional) Filters issue based on status. Can only be: "draft", "published" or "scheduled"'
            example: null
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    -
                      id: 16730
                      subject: 'Sed qui facilis recusandae rerum.'
                      number: 1
                      description: null
                      created_at: '2026-02-21T23:34:05.000000Z'
                      updated_at: '2026-02-21T23:34:05.000000Z'
                      published_at: '2026-02-21T23:34:05.000000Z'
                      is_published: true
                      is_scheduled: false
                    -
                      id: 16731
                      subject: 'Est facere et eos aliquid non.'
                      number: 1
                      description: null
                      created_at: '2026-02-21T23:34:05.000000Z'
                      updated_at: '2026-02-21T23:34:05.000000Z'
                      published_at: '2026-02-21T23:34:05.000000Z'
                      is_published: true
                      is_scheduled: false
                  links:
                    first: '/?page=1'
                    last: null
                    prev: null
                    next: null
                  meta:
                    current_page: 1
                    current_page_url: '/?page=1'
                    from: 1
                    path: /
                    per_page: '50'
                    to: 2
                properties:
                  data:
                    type: array
                    example:
                      -
                        id: 16730
                        subject: 'Sed qui facilis recusandae rerum.'
                        number: 1
                        description: null
                        created_at: '2026-02-21T23:34:05.000000Z'
                        updated_at: '2026-02-21T23:34:05.000000Z'
                        published_at: '2026-02-21T23:34:05.000000Z'
                        is_published: true
                        is_scheduled: false
                      -
                        id: 16731
                        subject: 'Est facere et eos aliquid non.'
                        number: 1
                        description: null
                        created_at: '2026-02-21T23:34:05.000000Z'
                        updated_at: '2026-02-21T23:34:05.000000Z'
                        published_at: '2026-02-21T23:34:05.000000Z'
                        is_published: true
                        is_scheduled: false
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          example: 16730
                        subject:
                          type: string
                          example: 'Sed qui facilis recusandae rerum.'
                        number:
                          type: integer
                          example: 1
                        description:
                          type: string
                          example: null
                          nullable: true
                        created_at:
                          type: string
                          example: '2026-02-21T23:34:05.000000Z'
                        updated_at:
                          type: string
                          example: '2026-02-21T23:34:05.000000Z'
                        published_at:
                          type: string
                          example: '2026-02-21T23:34:05.000000Z'
                        is_published:
                          type: boolean
                          example: true
                        is_scheduled:
                          type: boolean
                          example: false
                  links:
                    type: object
                    properties:
                      first:
                        type: string
                        example: '/?page=1'
                      last:
                        type: string
                        example: null
                        nullable: true
                      prev:
                        type: string
                        example: null
                        nullable: true
                      next:
                        type: string
                        example: null
                        nullable: true
                  meta:
                    type: object
                    properties:
                      current_page:
                        type: integer
                        example: 1
                      current_page_url:
                        type: string
                        example: '/?page=1'
                      from:
                        type: integer
                        example: 1
                      path:
                        type: string
                        example: /
                      per_page:
                        type: string
                        example: '50'
                      to:
                        type: integer
                        example: 2
      tags:
        - Issues
  '/api/v1/issues/{issue_id}':
    get:
      summary: 'Fetch the specified issue.'
      operationId: fetchTheSpecifiedIssue
      description: ''
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  id: 16732
                  subject: 'Aut hic sed id.'
                  number: 1
                  description: null
                  html_content: "<!-- Main table -->\n<table dir=\"rtl\" margin=\"0\" border=\"0\" cellspacing=\"0\" cellpadding=\"0\" align=\"center\" width=\"100%\">\n  <tbody>\n    <tr>\n  <td align=\"center\">\n    <h1\n      style=\"font-family: inherit; font-weight:bold; font-size:30px; color:#18181B; padding:0; padding-bottom: 0px; margin:0;\">\n      Aut hic sed id.\n    </h1>\n  </td>\n</tr>\n<tr>\n  <td height=\"5\"></td>\n</tr>\n<tr>\n  <td align=\"center\"\n    style=\"font-family: inherit; font-size:14px; font-weight:bold; color: #8d78a5; \"\n    >\n\n              <span>بواسطة خُزامى</span>\n      <span style=\"padding: 0 5px;\">•</span>\n        <span>#العدد 1</span>\n    <span style=\"padding: 0 5px;\">•</span>\n    <a href=\"http://gohodhod.com/@khuzzama/issues/16732\" style=\"color: #8d78a5\" target=\"_blank\">\n      عرض في المتصفح\n    </a>\n  </td>\n</tr>\n\n\n<tr>\n  <td height=\"20\"></td>\n</tr>\n<tr>\n  <td align=\"center\">\n    <hr style=\"height: 3px; width:75px; background-color:#d4d4d8; border: 0; border-radius: 100px;\">\n  </td>\n</tr>\n<tr>\n  <td height=\"20\"></td>\n</tr>\n\n  </tbody>\n</table>\n<style>\n  .dark .article-dynamic-data span,\n  .dark .article-dynamic-data font {\n    color: #e1e1e1 !important;\n  }\n</style>"
                  created_at: '2026-02-21T23:34:06.000000Z'
                  updated_at: '2026-02-21T23:34:06.000000Z'
                  published_at: null
                  is_published: false
                  is_scheduled: false
                properties:
                  id:
                    type: integer
                    example: 16732
                  subject:
                    type: string
                    example: 'Aut hic sed id.'
                  number:
                    type: integer
                    example: 1
                  description:
                    type: string
                    example: null
                    nullable: true
                  html_content:
                    type: string
                    example: "<!-- Main table -->\n<table dir=\"rtl\" margin=\"0\" border=\"0\" cellspacing=\"0\" cellpadding=\"0\" align=\"center\" width=\"100%\">\n  <tbody>\n    <tr>\n  <td align=\"center\">\n    <h1\n      style=\"font-family: inherit; font-weight:bold; font-size:30px; color:#18181B; padding:0; padding-bottom: 0px; margin:0;\">\n      Aut hic sed id.\n    </h1>\n  </td>\n</tr>\n<tr>\n  <td height=\"5\"></td>\n</tr>\n<tr>\n  <td align=\"center\"\n    style=\"font-family: inherit; font-size:14px; font-weight:bold; color: #8d78a5; \"\n    >\n\n              <span>بواسطة خُزامى</span>\n      <span style=\"padding: 0 5px;\">•</span>\n        <span>#العدد 1</span>\n    <span style=\"padding: 0 5px;\">•</span>\n    <a href=\"http://gohodhod.com/@khuzzama/issues/16732\" style=\"color: #8d78a5\" target=\"_blank\">\n      عرض في المتصفح\n    </a>\n  </td>\n</tr>\n\n\n<tr>\n  <td height=\"20\"></td>\n</tr>\n<tr>\n  <td align=\"center\">\n    <hr style=\"height: 3px; width:75px; background-color:#d4d4d8; border: 0; border-radius: 100px;\">\n  </td>\n</tr>\n<tr>\n  <td height=\"20\"></td>\n</tr>\n\n  </tbody>\n</table>\n<style>\n  .dark .article-dynamic-data span,\n  .dark .article-dynamic-data font {\n    color: #e1e1e1 !important;\n  }\n</style>"
                  created_at:
                    type: string
                    example: '2026-02-21T23:34:06.000000Z'
                  updated_at:
                    type: string
                    example: '2026-02-21T23:34:06.000000Z'
                  published_at:
                    type: string
                    example: null
                    nullable: true
                  is_published:
                    type: boolean
                    example: false
                  is_scheduled:
                    type: boolean
                    example: false
      tags:
        - Issues
    delete:
      summary: 'Remove the specified issue from storage.'
      operationId: removeTheSpecifiedIssueFromStorage
      description: ''
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: boolean
                example: true
      tags:
        - Issues
    parameters:
      -
        in: path
        name: issue_id
        description: 'The ID of the issue.'
        example: 3
        required: true
        schema:
          type: integer
  '/api/v1/issues/{issue_id}/publish':
    post:
      summary: 'Publish the specified issue immediatly.'
      operationId: publishTheSpecifiedIssueImmediatly
      description: ''
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: boolean
                example: true
      tags:
        - Issues
    parameters:
      -
        in: path
        name: issue_id
        description: 'The ID of the issue.'
        example: 3
        required: true
        schema:
          type: integer
  '/api/v1/issues/{issue_id}/schedule':
    post:
      summary: 'Schedue the specified issue for publish.'
      operationId: schedueTheSpecifiedIssueForPublish
      description: ''
      parameters:
        -
          in: query
          name: published_at
          description: 'The date and time when the issue should be published. Should be a valid datetime string and in the future (after current datetime).'
          example: '2023-01-01 00:00:00'
          required: true
          schema:
            type: string
            description: 'The date and time when the issue should be published. Should be a valid datetime string and in the future (after current datetime).'
            example: '2023-01-01 00:00:00'
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: boolean
                example: true
      tags:
        - Issues
    parameters:
      -
        in: path
        name: issue_id
        description: 'The ID of the issue.'
        example: 3
        required: true
        schema:
          type: integer
  '/api/v1/issues/{issue_id}/cancel-schedule':
    post:
      summary: 'Cancel scheduling for the specified issue.'
      operationId: cancelSchedulingForTheSpecifiedIssue
      description: ''
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: boolean
                example: true
      tags:
        - Issues
    parameters:
      -
        in: path
        name: issue_id
        description: 'The ID of the issue.'
        example: 3
        required: true
        schema:
          type: integer
  /api/v1/subscribers:
    get:
      summary: "Fetch a listing of newsletter's subscribers."
      operationId: fetchAListingOfNewslettersSubscribers
      description: ''
      parameters:
        -
          in: query
          name: status
          description: '(optional) Filters subscribers based on status. Can only be: "subscribed", "unsubscribed" or "supressed"'
          example: null
          required: false
          schema:
            type: string
            description: '(optional) Filters subscribers based on status. Can only be: "subscribed", "unsubscribed" or "supressed"'
            example: null
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  data:
                    -
                      id: 1082714
                      email: saleem52@example.com
                      first_name: سائد
                      last_name: برماوي
                      source: import
                      created_at: '2026-02-21T23:34:05.000000Z'
                      updated_at: '2026-02-21T23:34:05.000000Z'
                      unsubscribed_at: null
                      suppressed_at: null
                    -
                      id: 1082715
                      email: saleem.hamad@example.com
                      first_name: سهيله
                      last_name: الزامل
                      source: profile
                      created_at: '2026-02-21T23:34:05.000000Z'
                      updated_at: '2026-02-21T23:34:05.000000Z'
                      unsubscribed_at: null
                      suppressed_at: null
                  links:
                    first: '/?page=1'
                    last: null
                    prev: null
                    next: null
                  meta:
                    current_page: 1
                    current_page_url: '/?page=1'
                    from: 1
                    path: /
                    per_page: '50'
                    to: 2
                properties:
                  data:
                    type: array
                    example:
                      -
                        id: 1082714
                        email: saleem52@example.com
                        first_name: سائد
                        last_name: برماوي
                        source: import
                        created_at: '2026-02-21T23:34:05.000000Z'
                        updated_at: '2026-02-21T23:34:05.000000Z'
                        unsubscribed_at: null
                        suppressed_at: null
                      -
                        id: 1082715
                        email: saleem.hamad@example.com
                        first_name: سهيله
                        last_name: الزامل
                        source: profile
                        created_at: '2026-02-21T23:34:05.000000Z'
                        updated_at: '2026-02-21T23:34:05.000000Z'
                        unsubscribed_at: null
                        suppressed_at: null
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          example: 1082714
                        email:
                          type: string
                          example: saleem52@example.com
                        first_name:
                          type: string
                          example: سائد
                        last_name:
                          type: string
                          example: برماوي
                        source:
                          type: string
                          example: import
                        created_at:
                          type: string
                          example: '2026-02-21T23:34:05.000000Z'
                        updated_at:
                          type: string
                          example: '2026-02-21T23:34:05.000000Z'
                        unsubscribed_at:
                          type: string
                          example: null
                          nullable: true
                        suppressed_at:
                          type: string
                          example: null
                          nullable: true
                  links:
                    type: object
                    properties:
                      first:
                        type: string
                        example: '/?page=1'
                      last:
                        type: string
                        example: null
                        nullable: true
                      prev:
                        type: string
                        example: null
                        nullable: true
                      next:
                        type: string
                        example: null
                        nullable: true
                  meta:
                    type: object
                    properties:
                      current_page:
                        type: integer
                        example: 1
                      current_page_url:
                        type: string
                        example: '/?page=1'
                      from:
                        type: integer
                        example: 1
                      path:
                        type: string
                        example: /
                      per_page:
                        type: string
                        example: '50'
                      to:
                        type: integer
                        example: 2
      tags:
        - Subscribers
    post:
      summary: 'Store a newly created subscriber in storage.'
      operationId: storeANewlyCreatedSubscriberInStorage
      description: ''
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: boolean
                example: true
      tags:
        - Subscribers
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  description: 'يجب أن يكون value عنوان بريد إلكتروني صحيح البُنية.'
                  example: jaclyn18@example.com
                first_name:
                  type: string
                  description: ''
                  example: et
                  nullable: true
                last_name:
                  type: string
                  description: ''
                  example: perspiciatis
                  nullable: true
                source:
                  type: string
                  description: ''
                  example: veniam
                  nullable: true
                unsubscribed_at:
                  type: string
                  description: 'value ليس تاريخًا صحيحًا.'
                  example: '2026-02-21T23:34:05'
                  nullable: true
                suppressed_at:
                  type: string
                  description: 'value ليس تاريخًا صحيحًا.'
                  example: '2026-02-21T23:34:05'
                  nullable: true
              required:
                - email
  '/api/v1/subscribers/{subscriber_id}':
    get:
      summary: 'Fetch the specified subscriber.'
      operationId: fetchTheSpecifiedSubscriber
      description: ''
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: object
                example:
                  id: 1082716
                  email: fadi.nimry@example.net
                  first_name: نسيمة
                  last_name: هوساوي
                  source: profile
                  created_at: '2026-02-21T23:34:05.000000Z'
                  updated_at: '2026-02-21T23:34:05.000000Z'
                  unsubscribed_at: '2026-02-21T23:34:05.000000Z'
                  suppressed_at: '2026-02-21T23:34:05.000000Z'
                properties:
                  id:
                    type: integer
                    example: 1082716
                  email:
                    type: string
                    example: fadi.nimry@example.net
                  first_name:
                    type: string
                    example: نسيمة
                  last_name:
                    type: string
                    example: هوساوي
                  source:
                    type: string
                    example: profile
                  created_at:
                    type: string
                    example: '2026-02-21T23:34:05.000000Z'
                  updated_at:
                    type: string
                    example: '2026-02-21T23:34:05.000000Z'
                  unsubscribed_at:
                    type: string
                    example: '2026-02-21T23:34:05.000000Z'
                  suppressed_at:
                    type: string
                    example: '2026-02-21T23:34:05.000000Z'
      tags:
        - Subscribers
    put:
      summary: 'Update the specified subscriber in storage.'
      operationId: updateTheSpecifiedSubscriberInStorage
      description: ''
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: boolean
                example: true
      tags:
        - Subscribers
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                email:
                  type: string
                  description: 'يجب أن يكون value عنوان بريد إلكتروني صحيح البُنية.'
                  example: aimee64@example.com
                first_name:
                  type: string
                  description: ''
                  example: sunt
                  nullable: true
                last_name:
                  type: string
                  description: ''
                  example: aliquid
                  nullable: true
                source:
                  type: string
                  description: ''
                  example: doloremque
                  nullable: true
                unsubscribed_at:
                  type: string
                  description: 'value ليس تاريخًا صحيحًا.'
                  example: '2026-02-21T23:34:05'
                  nullable: true
                suppressed_at:
                  type: string
                  description: 'value ليس تاريخًا صحيحًا.'
                  example: '2026-02-21T23:34:05'
                  nullable: true
    delete:
      summary: 'Remove the specified subscriber from storage.'
      operationId: removeTheSpecifiedSubscriberFromStorage
      description: ''
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: boolean
                example: true
      tags:
        - Subscribers
    parameters:
      -
        in: path
        name: subscriber_id
        description: 'The ID of the subscriber.'
        example: 1
        required: true
        schema:
          type: integer
  '/api/v1/subscribers/{subscriber_id}/unsubscribe':
    post:
      summary: 'Unsubscribe the specified subscriber from the newsletter.'
      operationId: unsubscribeTheSpecifiedSubscriberFromTheNewsletter
      description: ''
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: boolean
                example: true
      tags:
        - Subscribers
    parameters:
      -
        in: path
        name: subscriber_id
        description: 'The ID of the subscriber.'
        example: 1
        required: true
        schema:
          type: integer
  '/api/v1/subscribers/{subscriber_id}/resubscribe':
    post:
      summary: 'Resubscribe the specified subscriber to the newsletter.'
      operationId: resubscribeTheSpecifiedSubscriberToTheNewsletter
      description: ''
      parameters: []
      responses:
        200:
          description: ''
          content:
            application/json:
              schema:
                type: boolean
                example: true
      tags:
        - Subscribers
    parameters:
      -
        in: path
        name: subscriber_id
        description: 'The ID of the subscriber.'
        example: 1
        required: true
        schema:
          type: integer