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: 7797
                  title: 'Voluptas nesciunt quasi rerum voluptas.'
                  author: 'سميرة الداوود'
                  description: 'Consequatur ut est quibusdam molestiae eveniet dicta itaque inventore qui quia.'
                  image: 'https://gohodhod.com/images/img-avatar-newsletter.png'
                  primary_color: '#13b981'
                  slug: abd.nimry
                  profile_url: 'https://gohodhod.com/@abd.nimry'
                  externa_links: null
                properties:
                  newsletter_id:
                    type: integer
                    example: 7797
                  title:
                    type: string
                    example: 'Voluptas nesciunt quasi rerum voluptas.'
                  author:
                    type: string
                    example: 'سميرة الداوود'
                  description:
                    type: string
                    example: 'Consequatur ut est quibusdam molestiae eveniet dicta itaque inventore qui quia.'
                  image:
                    type: string
                    example: 'https://gohodhod.com/images/img-avatar-newsletter.png'
                  primary_color:
                    type: string
                    example: '#13b981'
                  slug:
                    type: string
                    example: abd.nimry
                  profile_url:
                    type: string
                    example: 'https://gohodhod.com/@abd.nimry'
                  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: 'Dicta quia repudiandae et.'
                  nullable: true
                primary_color:
                  type: string
                  description: '(hex) يجب أن يكون كود لوني صحيح'
                  example: '#146ec2'
                  nullable: true
                slug:
                  type: string
                  description: 'لاحقة النشرة على هدهد (يمكن أن تحوي فقط أحرف لاتينية، أرقام، شرطة أفقية أو شرطة تحتية؟)'
                  example: architecto
  /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: 17078
                      subject: 'Deleniti aliquam qui non qui.'
                      number: 1
                      description: null
                      created_at: '2026-03-27T01:06:34.000000Z'
                      updated_at: '2026-03-27T01:06:34.000000Z'
                      published_at: '2026-03-27T01:06:34.000000Z'
                      is_published: true
                      is_scheduled: false
                    -
                      id: 17079
                      subject: 'Amet assumenda ut et ipsa consectetur autem eligendi.'
                      number: 1
                      description: null
                      created_at: '2026-03-27T01:06:34.000000Z'
                      updated_at: '2026-03-27T01:06:34.000000Z'
                      published_at: '2026-03-27T01:06:34.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: 17078
                        subject: 'Deleniti aliquam qui non qui.'
                        number: 1
                        description: null
                        created_at: '2026-03-27T01:06:34.000000Z'
                        updated_at: '2026-03-27T01:06:34.000000Z'
                        published_at: '2026-03-27T01:06:34.000000Z'
                        is_published: true
                        is_scheduled: false
                      -
                        id: 17079
                        subject: 'Amet assumenda ut et ipsa consectetur autem eligendi.'
                        number: 1
                        description: null
                        created_at: '2026-03-27T01:06:34.000000Z'
                        updated_at: '2026-03-27T01:06:34.000000Z'
                        published_at: '2026-03-27T01:06:34.000000Z'
                        is_published: true
                        is_scheduled: false
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          example: 17078
                        subject:
                          type: string
                          example: 'Deleniti aliquam qui non qui.'
                        number:
                          type: integer
                          example: 1
                        description:
                          type: string
                          example: null
                          nullable: true
                        created_at:
                          type: string
                          example: '2026-03-27T01:06:34.000000Z'
                        updated_at:
                          type: string
                          example: '2026-03-27T01:06:34.000000Z'
                        published_at:
                          type: string
                          example: '2026-03-27T01:06:34.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: 17080
                  subject: 'Pariatur nulla est adipisci rerum consequatur qui voluptatem odio.'
                  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      Pariatur nulla est adipisci rerum consequatur qui voluptatem odio.\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: #13b981; \"\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/@mr.aalomari3870/issues/17080\" style=\"color: #13b981\" 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-03-27T01:06:34.000000Z'
                  updated_at: '2026-03-27T01:06:34.000000Z'
                  published_at: null
                  is_published: false
                  is_scheduled: false
                properties:
                  id:
                    type: integer
                    example: 17080
                  subject:
                    type: string
                    example: 'Pariatur nulla est adipisci rerum consequatur qui voluptatem odio.'
                  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      Pariatur nulla est adipisci rerum consequatur qui voluptatem odio.\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: #13b981; \"\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/@mr.aalomari3870/issues/17080\" style=\"color: #13b981\" 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-03-27T01:06:34.000000Z'
                  updated_at:
                    type: string
                    example: '2026-03-27T01:06:34.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: 1084830
                      email: sami31@example.org
                      first_name: عون
                      last_name: العسكر
                      source: profile
                      created_at: '2026-03-27T01:06:34.000000Z'
                      updated_at: '2026-03-27T01:06:34.000000Z'
                      unsubscribed_at: null
                      suppressed_at: null
                    -
                      id: 1084831
                      email: abdullah.hamad@example.com
                      first_name: أحمد
                      last_name: الصقيه
                      source: dashboard
                      created_at: '2026-03-27T01:06:34.000000Z'
                      updated_at: '2026-03-27T01:06:34.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: 1084830
                        email: sami31@example.org
                        first_name: عون
                        last_name: العسكر
                        source: profile
                        created_at: '2026-03-27T01:06:34.000000Z'
                        updated_at: '2026-03-27T01:06:34.000000Z'
                        unsubscribed_at: null
                        suppressed_at: null
                      -
                        id: 1084831
                        email: abdullah.hamad@example.com
                        first_name: أحمد
                        last_name: الصقيه
                        source: dashboard
                        created_at: '2026-03-27T01:06:34.000000Z'
                        updated_at: '2026-03-27T01:06:34.000000Z'
                        unsubscribed_at: null
                        suppressed_at: null
                    items:
                      type: object
                      properties:
                        id:
                          type: integer
                          example: 1084830
                        email:
                          type: string
                          example: sami31@example.org
                        first_name:
                          type: string
                          example: عون
                        last_name:
                          type: string
                          example: العسكر
                        source:
                          type: string
                          example: profile
                        created_at:
                          type: string
                          example: '2026-03-27T01:06:34.000000Z'
                        updated_at:
                          type: string
                          example: '2026-03-27T01:06:34.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: danny64@example.org
                first_name:
                  type: string
                  description: ''
                  example: ab
                  nullable: true
                last_name:
                  type: string
                  description: ''
                  example: blanditiis
                  nullable: true
                source:
                  type: string
                  description: ''
                  example: est
                  nullable: true
                unsubscribed_at:
                  type: string
                  description: 'value ليس تاريخًا صحيحًا.'
                  example: '2026-03-27T01:06:34'
                  nullable: true
                suppressed_at:
                  type: string
                  description: 'value ليس تاريخًا صحيحًا.'
                  example: '2026-03-27T01:06:34'
                  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: 1084832
                  email: abbad.samer@example.org
                  first_name: حسن
                  last_name: السيف
                  source: dashboard
                  created_at: '2026-03-27T01:06:34.000000Z'
                  updated_at: '2026-03-27T01:06:34.000000Z'
                  unsubscribed_at: null
                  suppressed_at: null
                properties:
                  id:
                    type: integer
                    example: 1084832
                  email:
                    type: string
                    example: abbad.samer@example.org
                  first_name:
                    type: string
                    example: حسن
                  last_name:
                    type: string
                    example: السيف
                  source:
                    type: string
                    example: dashboard
                  created_at:
                    type: string
                    example: '2026-03-27T01:06:34.000000Z'
                  updated_at:
                    type: string
                    example: '2026-03-27T01:06:34.000000Z'
                  unsubscribed_at:
                    type: string
                    example: null
                    nullable: true
                  suppressed_at:
                    type: string
                    example: null
                    nullable: true
      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: urippin@example.net
                first_name:
                  type: string
                  description: ''
                  example: consequatur
                  nullable: true
                last_name:
                  type: string
                  description: ''
                  example: placeat
                  nullable: true
                source:
                  type: string
                  description: ''
                  example: nihil
                  nullable: true
                unsubscribed_at:
                  type: string
                  description: 'value ليس تاريخًا صحيحًا.'
                  example: '2026-03-27T01:06:34'
                  nullable: true
                suppressed_at:
                  type: string
                  description: 'value ليس تاريخًا صحيحًا.'
                  example: '2026-03-27T01:06:34'
                  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