lovefengis-com Catalog API

openapi: 3.2.0
info:
  title: lovefengis public Catalog API
  version: 1.0.0
  description: 'Catalog of the services and prices of lovefengis, an ads management and SEO agency in Turkey. Prices come from the same source as the website (TRY, VAT included). No authentication, no personal data. Every operation is read-only: the two POST endpoints (/batch and /jobs) only run reads and compute exports, they store and change nothing. To start a project, book a call at /gorusme.


    Pagination: list endpoints take limit (1-100, default 50) and an opaque cursor, and return next_cursor (null on the last page) and has_more.


    Idempotency: every POST accepts an Idempotency-Key header (1 to 255 printable ASCII characters). Operations are deterministic, so a repeated key with the same body returns the same result; the key is echoed in the response.


    Sandbox: the second server serves the same API with fixture data (two fake services, ids starting with sandbox-). Responses carry X-Lovefengis-Environment: sandbox. The short form /api/sandbox/v1 also works.


    Versioning: the major version is in the path (/api/v1). Breaking changes ship as a new path; a deprecated endpoint keeps working for at least 6 months and announces itself with Deprecation, Sunset and Link headers. Policy: https://lovefengis.com/gelistirici/surum-politikasi'
  contact:
    name: lovefengis
    url: https://lovefengis.com/gorusme
  x-deprecation-policy: https://lovefengis.com/gelistirici/surum-politikasi
servers:
- url: https://lovefengis.com
  description: Production
- url: https://sandbox.lovefengis.com
  description: 'Sandbox server: same API paths with fake fixture data (also at ${SITE}/api/sandbox/v1)'
tags:
- name: Catalog
  description: Services and prices
paths:
  /api/v1:
    get:
      operationId: getApiIndex
      tags:
      - Catalog
      summary: API index
      description: Returns the API name, version, documentation links and the list of available endpoints.
      parameters:
      - name: API-Version
        in: header
        required: false
        description: 'Pin the API version. Optional; the only version is 1. Any other value returns 400 unsupported_api_version. Policy: https://lovefengis.com/gelistirici/surum-politikasi'
        schema:
          type: string
          enum:
          - '1'
      responses:
        '200':
          description: API index
          headers:
            API-Version:
              description: Version that served the response.
              schema:
                type: string
            Deprecation:
              description: 'RFC 9745. Present only on a deprecated endpoint: @ followed by the Unix time of deprecation.'
              schema:
                type: string
            Sunset:
              description: 'RFC 8594. Present only on a deprecated endpoint: HTTP date after which it may stop working.'
              schema:
                type: string
            Link:
              description: 'On a deprecated endpoint: the deprecation policy, rel="deprecation".'
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                required:
                - name
                - version
                - openapi
                - docs
                - deprecation_policy
                - endpoints
                properties:
                  name:
                    type: string
                  version:
                    type: string
                  openapi:
                    type: string
                    format: uri
                  docs:
                    type: string
                    format: uri
                    description: Developer documentation.
                  deprecation_policy:
                    type: string
                    format: uri
                  sandbox:
                    type: string
                    format: uri
                    description: Base URL of the sandbox that serves fixture data.
                  endpoints:
                    type: array
                    items:
                      type: object
                      required:
                      - method
                      - path
                      - description
                      properties:
                        method:
                          type: string
                          enum:
                          - GET
                          - POST
                        path:
                          type: string
                        description:
                          type: string
        '400':
          description: A parameter or the API-Version header is not valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded; retry after the Retry-After header.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/status:
    get:
      operationId: getStatus
      tags:
      - Catalog
      summary: Health check
      description: Returns status ok, the API version and the server time. Never cached.
      parameters:
      - name: API-Version
        in: header
        required: false
        description: 'Pin the API version. Optional; the only version is 1. Any other value returns 400 unsupported_api_version. Policy: https://lovefengis.com/gelistirici/surum-politikasi'
        schema:
          type: string
          enum:
          - '1'
      responses:
        '200':
          description: Health status
          headers:
            API-Version:
              description: Version that served the response.
              schema:
                type: string
            Deprecation:
              description: 'RFC 9745. Present only on a deprecated endpoint: @ followed by the Unix time of deprecation.'
              schema:
                type: string
            Sunset:
              description: 'RFC 8594. Present only on a deprecated endpoint: HTTP date after which it may stop working.'
              schema:
                type: string
            Link:
              description: 'On a deprecated endpoint: the deprecation policy, rel="deprecation".'
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                required:
                - status
                - version
                - time
                properties:
                  status:
                    type: string
                    const: ok
                  version:
                    type: string
                    example: v1
                  time:
                    type: string
                    format: date-time
        '400':
          description: A parameter or the API-Version header is not valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded; retry after the Retry-After header.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/hizmetler:
    get:
      operationId: listServices
      tags:
      - Catalog
      summary: List services
      description: Returns services with their id, page URL, Markdown URL and prices, one page at a time (limit, cursor).
      parameters:
      - name: limit
        in: query
        required: false
        description: Maximum items per page, 1 to 100. Default 50.
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 50
      - name: cursor
        in: query
        required: false
        description: Opaque cursor. Pass the next_cursor value of the previous response of the same endpoint, unchanged, to get the next page.
        schema:
          type: string
          maxLength: 64
      - name: API-Version
        in: header
        required: false
        description: 'Pin the API version. Optional; the only version is 1. Any other value returns 400 unsupported_api_version. Policy: https://lovefengis.com/gelistirici/surum-politikasi'
        schema:
          type: string
          enum:
          - '1'
      responses:
        '200':
          description: Service list page
          headers:
            API-Version:
              description: Version that served the response.
              schema:
                type: string
            Deprecation:
              description: 'RFC 9745. Present only on a deprecated endpoint: @ followed by the Unix time of deprecation.'
              schema:
                type: string
            Sunset:
              description: 'RFC 8594. Present only on a deprecated endpoint: HTTP date after which it may stop working.'
              schema:
                type: string
            Link:
              description: 'On a deprecated endpoint: the deprecation policy, rel="deprecation".'
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                - next_cursor
                - has_more
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ServiceSummary'
                  meta:
                    $ref: '#/components/schemas/Meta'
                  next_cursor:
                    type:
                    - string
                    - 'null'
                    description: Pass as the cursor query parameter to get the next page. null on the last page.
                  has_more:
                    type: boolean
                    description: true when another page follows.
        '400':
          description: A parameter or the API-Version header is not valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded; retry after the Retry-After header.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/hizmetler/{id}:
    get:
      operationId: getService
      tags:
      - Catalog
      summary: Get one service
      description: Returns one service with prices and, where the catalog has it, the scope list.
      parameters:
      - name: id
        in: path
        required: true
        description: Service id, the last segment of the service page path (for example reklam-yonetimi).
        schema:
          type: string
          pattern: ^[a-z0-9]+(-[a-z0-9]+)*$
          maxLength: 80
      - name: API-Version
        in: header
        required: false
        description: 'Pin the API version. Optional; the only version is 1. Any other value returns 400 unsupported_api_version. Policy: https://lovefengis.com/gelistirici/surum-politikasi'
        schema:
          type: string
          enum:
          - '1'
      responses:
        '200':
          description: Service
          headers:
            API-Version:
              description: Version that served the response.
              schema:
                type: string
            Deprecation:
              description: 'RFC 9745. Present only on a deprecated endpoint: @ followed by the Unix time of deprecation.'
              schema:
                type: string
            Sunset:
              description: 'RFC 8594. Present only on a deprecated endpoint: HTTP date after which it may stop working.'
              schema:
                type: string
            Link:
              description: 'On a deprecated endpoint: the deprecation policy, rel="deprecation".'
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                properties:
                  data:
                    $ref: '#/components/schemas/Service'
                  meta:
                    $ref: '#/components/schemas/Meta'
        '400':
          description: A parameter or the API-Version header is not valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: No service has this id.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded; retry after the Retry-After header.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/fiyatlar:
    get:
      operationId: listPrices
      tags:
      - Catalog
      summary: List prices
      description: Returns a flat list of prices. Each price carries its service id. Filter by service id and billing period. Paged with limit and cursor.
      parameters:
      - name: service
        in: query
        required: false
        description: Only prices of this service id.
        schema:
          type: string
          pattern: ^[a-z0-9]+(-[a-z0-9]+)*$
          maxLength: 80
      - name: period
        in: query
        required: false
        description: Only prices with this billing period.
        schema:
          type: string
          enum:
          - one_time
          - monthly
          - yearly
      - name: limit
        in: query
        required: false
        description: Maximum items per page, 1 to 100. Default 50.
        schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 50
      - name: cursor
        in: query
        required: false
        description: Opaque cursor. Pass the next_cursor value of the previous response of the same endpoint, unchanged, to get the next page.
        schema:
          type: string
          maxLength: 64
      - name: API-Version
        in: header
        required: false
        description: 'Pin the API version. Optional; the only version is 1. Any other value returns 400 unsupported_api_version. Policy: https://lovefengis.com/gelistirici/surum-politikasi'
        schema:
          type: string
          enum:
          - '1'
      responses:
        '200':
          description: Price list page
          headers:
            API-Version:
              description: Version that served the response.
              schema:
                type: string
            Deprecation:
              description: 'RFC 9745. Present only on a deprecated endpoint: @ followed by the Unix time of deprecation.'
              schema:
                type: string
            Sunset:
              description: 'RFC 8594. Present only on a deprecated endpoint: HTTP date after which it may stop working.'
              schema:
                type: string
            Link:
              description: 'On a deprecated endpoint: the deprecation policy, rel="deprecation".'
              schema:
                type: string
          content:
            application/json:
              schema:
                type: object
                required:
                - data
                - meta
                - next_cursor
                - has_more
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/PriceWithService'
                  meta:
                    $ref: '#/components/schemas/Meta'
                  next_cursor:
                    type:
                    - string
                    - 'null'
                    description: Pass as the cursor query parameter to get the next page. null on the last page.
                  has_more:
                    type: boolean
                    description: true when another page follows.
        '400':
          description: A parameter or the API-Version header is not valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: Rate limit exceeded; retry after the Retry-After header.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    Meta:
      type: object
      required:
      - currency
      - vat_included
      - vat_note
      - from_means
      - fx
      - source
      properties:
        currency:
          type: string
          const: TRY
        vat_included:
          type: boolean
        vat_note:
          type: string
        from_means:
          type: string
        fx:
          type: object
          required:
          - usd_try
          - as_of
          - source
          properties:
            usd_try:
              type: number
            as_of:
              type: string
            source:
              type: string
        source:
          type: string
          format: uri
        environment:
          type: string
          const: sandbox
          description: Present only in sandbox responses.
        note:
          type: string
          description: 'Present only in sandbox responses: the data is fake.'
    ServiceSummary:
      type: object
      required:
      - id
      - name
      - url
      - markdown_url
      - prices
      properties:
        id:
          type: string
        name:
          type: string
        url:
          type: string
          format: uri
        markdown_url:
          type: string
          format: uri
        prices:
          type: array
          items:
            $ref: '#/components/schemas/Price'
    PriceWithService:
      allOf:
      - $ref: '#/components/schemas/Price'
      - type: object
        required:
        - service_id
        - service_name
        - service_url
        properties:
          service_id:
            type: string
          service_name:
            type: string
          service_url:
            type: string
            format: uri
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          - hint
          properties:
            code:
              type: string
              description: Stable machine-readable code.
            message:
              type: string
            hint:
              type: string
              description: How to fix the request.
    Price:
      type: object
      required:
      - id
      - label
      - amount_try
      - type
      - period
      - delivery
      - commitment_months
      properties:
        id:
          type: string
        label:
          type: string
        amount_try:
          type: integer
          description: Amount in Turkish lira, VAT included.
        type:
          type: string
          enum:
          - fixed
          - from
          description: '"from" is a starting price; the final amount is fixed in a written offer.'
        period:
          type: string
          enum:
          - one_time
          - monthly
          - yearly
        delivery:
          type:
          - string
          - 'null'
          description: Delivery time as written on the site, or null.
        commitment_months:
          type:
          - integer
          - 'null'
    Service:
      allOf:
      - $ref: '#/components/schemas/ServiceSummary'
      - type: object
        required:
        - scope
        properties:
          scope:
            type:
            - array
            - 'null'
            items:
              type: string
            description: What the service includes, when the catalog lists it.
externalDocs:
  description: lovefengis developer docs
  url: https://lovefengis.com/gelistirici/api